ReachableCEO
937ec852eb
Add full demo environment with 13 services across 4 categories: - Infrastructure: Homepage, Docker Socket Proxy, Pi-hole, Portainer - Monitoring: InfluxDB, Grafana - Documentation: Draw.io, Kroki - Developer Tools: Atomic Tracker, ArchiveBox, Tube Archivist, Wakapi, MailHog, Atuin Includes: - Docker Compose templates with dynamic environment configuration - Deployment orchestration scripts with user ID detection - Comprehensive test suite (unit, integration, e2e) - Pre-deployment validation with yamllint, shellcheck - Full documentation (PRD, AGENTS, README) - Service configurations for all components All services configured for demo purposes with: - Dynamic UID/GID mapping - Docker socket proxy security - Health checks and monitoring - Service discovery via Homepage labels Ports allocated 4000-4099 range with sequential assignment. 💘 Generated with Crush Assisted-by: GLM-4.7 via Crush <crush@charm.land>
285 lines
7.2 KiB
Markdown
285 lines
7.2 KiB
Markdown
# 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
|
|
|
|
### Portainer
|
|
- **Base URL**: `http://localhost:4007`
|
|
- **API Version**: v2
|
|
- **Authentication**: Bearer token
|
|
- **Endpoints**:
|
|
- `POST /api/auth` - Authentication
|
|
- `GET /api/endpoints` - List endpoints
|
|
- `GET /api/containers` - List containers
|
|
- `GET /api/images` - List images
|
|
|
|
## 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 |