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://localhost:4005`
- **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**: Direct Docker API 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
```bash
# Get Docker version
curl http://localhost:4005/version

# List containers
curl http://localhost:4005/containers/json
```

### InfluxDB Example
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```json
{
  "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
```bash
# Test all health endpoints
for port in 4005 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