TSYSDevStack-SupportStack-LocalWorkstation/demo/docs/api-docs/README.md

TSYS Developer Support Stack - API Documentation

Service APIs Overview

This document provides API endpoint information for all services in the stack.

Infrastructure Services APIs

Docker Socket Proxy

• **Base URL: http://docker-socket-proxy:2375 (internal only, not accessible from host)`
• API Version: Docker Engine API
• Authentication: None (restricted by proxy)
• Endpoints:
  • GET /version - Docker version information
  • GET /info - System information
  • GET /containers/json - List containers
  • GET /images/json - List images

Pi-hole

• Base URL: http://localhost:4006/admin
• API Version: v1
• Authentication: Basic auth (demo_password)
• Endpoints:
  • GET /admin/api.php - Statistics and status
  • GET /admin/api.php?list - Blocked domains list
  • GET /admin/api.php?summaryRaw - Raw statistics

Dockhand

• Base URL: http://localhost:4007
• Authentication: Web UI with direct Docker socket access
• Features:
  • Container lifecycle management
  • Compose stack orchestration
  • Git-based deployments
  • Multi-environment support
  • Terminal access
  • Log streaming
  • File browser

Monitoring & Observability APIs

InfluxDB

• Base URL: http://localhost:4008
• API Version: v2
• Authentication: Token-based
• Endpoints:
  • GET /ping - Health check
  • POST /api/v2/write - Write data
  • GET /api/v2/query - Query data
  • GET /api/health - Health status

Grafana

• Base URL: http://localhost:4009
• API Version: v1
• Authentication: API key or Basic auth
• Endpoints:
  • GET /api/health - Health check
  • GET /api/dashboards - List dashboards
  • GET /api/datasources - List data sources
  • POST /api/login - Authentication

Documentation & Diagramming APIs

Draw.io

• Base URL: http://localhost:4010
• API Version: None (web interface)
• Authentication: None
• Endpoints:
  • GET / - Main interface
  • POST /export - Export diagram
  • GET /images - Image library

Kroki

• Base URL: http://localhost:4011
• API Version: v1
• Authentication: None
• Endpoints:
  • GET /health - Health check
  • POST /plantuml/svg - PlantUML to SVG
  • POST /mermaid/svg - Mermaid to SVG
  • POST /graphviz/svg - GraphViz to SVG

Developer Tools APIs

Homepage

• Base URL: http://localhost:4000
• API Version: None (web interface)
• Authentication: None
• Endpoints:
  • GET / - Main dashboard
  • GET /widgets - Widget data
  • GET /bookmarks - Bookmark data

Atomic Tracker

• Base URL: http://localhost:4012
• API Version: v1
• Authentication: Required
• Endpoints:
  • GET /api/habits - List habits
  • POST /api/habits - Create habit
  • PUT /api/habits/:id - Update habit
  • DELETE /api/habits/:id - Delete habit

ArchiveBox

• Base URL: http://localhost:4013
• API Version: v1
• Authentication: Required
• Endpoints:
  • GET /api/v1/core/health - Health check
  • POST /api/v1/core/add - Add URL
  • GET /api/v1/snapshots - List snapshots
  • GET /api/v1/snapshots/:id - Get snapshot

Tube Archivist

• Base URL: http://localhost:4014
• API Version: v1
• Authentication: Required
• Endpoints:
  • GET /api/health - Health check
  • POST /api/subscribe - Subscribe to channel
  • GET /api/video/:id - Get video info
  • GET /api/search - Search videos

Wakapi

• Base URL: http://localhost:4015
• API Version: v1
• Authentication: API key
• Endpoints:
  • GET /api/health - Heartbeat
  • GET /api/summary - Time summary
  • GET /api/durations - Heartbeats
  • POST /api/heartbeats - Add heartbeat

MailHog

• Base URL: http://localhost:4017
• API Version: v1
• Authentication: None
• Endpoints:
  • GET /api/v1/messages - List messages
  • GET /api/v1/messages/:id - Get message
  • DELETE /api/v1/messages - Delete all
  • POST /api/v1/messages - Create message

Atuin

• Base URL: http://localhost:4018
• API Version: v1
• Authentication: Required
• Endpoints:
  • GET /api/health - Health check
  • POST /api/sync - Sync history
  • GET /api/history - Get history
  • POST /api/history - Add history

API Usage Examples

Docker Socket Proxy Example

# Get Docker version
# curl http://localhost:4005/version  (internal only)

# List containers
# curl http://localhost:4005/containers/json  (internal only)

InfluxDB Example

# Write data
curl -X POST http://localhost:4008/api/v2/write \
  -H "Authorization: Token demo_token_replace_in_production" \
  -H "Content-Type: text/plain" \
  --data-binary "measurement,field=value"

# Query data
curl -G http://localhost:4008/api/v2/query \
  -H "Authorization: Token demo_token_replace_in_production" \
  --data-urlencode "query=from(bucket:\"demo_metrics\") |> range(start: -1h)"

Grafana Example

# Get dashboards
curl -u admin:demo_password http://localhost:4009/api/dashboards

# Create API key
curl -X POST -u admin:demo_password \
  http://localhost:4009/api/auth/keys \
  -H "Content-Type: application/json" \
  -d '{"name":"demo","role":"Admin"}'

Kroki Example

# Convert PlantUML to SVG
curl -X POST http://localhost:4011/plantuml/svg \
  -H "Content-Type: text/plain" \
  -d "@startuml
  Alice -> Bob: Hello
  @enduml"

Authentication

Demo Credentials

• Username: admin
• Password: demo_password
• API Keys: Use demo tokens provided in configuration

Token-based Authentication

# InfluxDB token
export INFLUX_TOKEN="demo_token_replace_in_production"

# Grafana API key
export GRAFANA_API_KEY="demo_api_key"

# Wakapi API key
export WAKAPI_API_KEY="demo_wakapi_key"

Rate Limiting

Most services have no rate limiting in demo mode. In production:

• Configure appropriate rate limits
• Implement authentication
• Set up monitoring
• Use reverse proxy for additional security

Error Handling

Common HTTP Status Codes

• 200 - Success
• 401 - Authentication required
• 403 - Forbidden
• 404 - Not found
• 500 - Internal server error

Error Response Format

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": "Additional details"
}

Health Checks

All services provide health check endpoints:

• GET /health - Standard health check
• GET /ping - Simple ping response
• GET /api/health - API-specific health

Development Notes

Testing APIs

# Test all health endpoints
for port in 4000 4006 4007 4008 4009 4010 4011 4012 4013 4014 4015 4017 4018; do
    echo "Testing port $port..."
    curl -f -s "http://localhost:$port/health" || \
    curl -f -s "http://localhost:$port/ping" || \
    curl -f -s "http://localhost:$port/api/health" || \
    echo "Health check failed for port $port"
done

Monitoring API Usage

• Use Grafana dashboards to monitor API calls
• Check service logs for API errors
• Monitor resource usage with Docker stats
• Set up alerts for API failures

Security Considerations

Demo Mode

• All APIs are accessible without authentication
• No rate limiting implemented
• No HTTPS encryption
• Default demo credentials

Production Migration

• Implement proper authentication
• Add rate limiting
• Use HTTPS/TLS
• Set up API gateway
• Implement audit logging
• Configure CORS policies