# API Design Document ## Base URL ``` Development: http://localhost:8000/api/v1 Production: https://api.planet.example.com/api/v1 WebSocket: ws://localhost:8000/ws ``` --- ## Authentication ### Login ```http POST /api/v1/auth/login Content-Type: application/json { "username": "admin", "password": "admin123" } ``` **Response (200 OK)** ```json { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "bearer", "expires_in": 900, "user": { "id": 1, "username": "admin", "role": "super_admin" } } ``` **Response (401 Unauthorized)** ```json { "detail": "Invalid credentials" } ``` ### Refresh Token ```http POST /api/v1/auth/refresh Authorization: Bearer ``` **Response (200 OK)** ```json { "access_token": "new_access_token", "expires_in": 900 } ``` ### Logout ```http POST /api/v1/auth/logout Authorization: Bearer ``` ### Get Current User ```http GET /api/v1/auth/me Authorization: Bearer ``` **Response (200 OK)** ```json { "id": 1, "username": "admin", "email": "admin@example.com", "role": "super_admin", "is_active": true, "created_at": "2024-01-15T10:00:00Z" } ``` --- ## Users Management ### List Users ```http GET /api/v1/users Authorization: Bearer Query Parameters: - page: int (default: 1) - page_size: int (default: 20, max: 100) - role: string (optional) - is_active: boolean (optional) - search: string (optional) ``` **Response (200 OK)** ```json { "total": 45, "page": 1, "page_size": 20, "data": [ { "id": 1, "username": "admin", "email": "admin@example.com", "role": "super_admin", "is_active": true, "last_login": "2024-01-20T15:30:00Z", "created_at": "2024-01-15T10:00:00Z" } ] } ``` ### Get User ```http GET /api/v1/users/{user_id} Authorization: Bearer ``` ### Create User ```http POST /api/v1/users Authorization: Bearer Content-Type: application/json { "username": "newuser", "email": "newuser@example.com", "password": "securepassword123", "role": "operator" } ``` **Response (201 Created)** ```json { "id": 46, "username": "newuser", "email": "newuser@example.com", "role": "operator", "is_active": true, "created_at": "2024-01-20T10:00:00Z" } ``` ### Update User ```http PUT /api/v1/users/{user_id} Authorization: Bearer Content-Type: application/json { "email": "updated@example.com", "role": "admin", "is_active": true } ``` ### Delete User ```http DELETE /api/v1/users/{user_id} Authorization: Bearer ``` ### Change Password ```http POST /api/v1/users/{user_id}/change-password Authorization: Bearer Content-Type: application/json { "old_password": "oldpassword", "new_password": "newpassword123" } ``` --- ## Data Sources ### List Data Sources ```http GET /api/v1/datasources Authorization: Bearer Query Parameters: - module: string (L1, L2, L3, L4) - is_active: boolean - priority: string (P0, P1) ``` **Response (200 OK)** ```json { "total": 9, "data": [ { "id": 1, "name": "TOP500", "module": "L1", "priority": "P0", "frequency": "4h", "is_active": true, "last_run": "2024-01-20T08:00:00Z", "last_status": "success", "next_run": "2024-01-20T12:00:00Z" } ] } ``` ### Get Data Source ```http GET /api/v1/datasources/{source_id} Authorization: Bearer ``` ### Create Data Source ```http POST /api/v1/datasources Authorization: Bearer Content-Type: application/json { "name": "New Source", "module": "L1", "priority": "P1", "frequency": "1h", "collector_class": "CustomCollector", "config": { "api_url": "https://api.example.com/data", "auth_type": "bearer", "api_key": "${env:API_KEY}" } } ``` ### Update Data Source ```http PUT /api/v1/datasources/{source_id} Authorization: Bearer Content-Type: application/json { "frequency": "30m", "is_active": true } ``` ### Enable/Disable Data Source ```http POST /api/v1/datasources/{source_id}/enable POST /api/v1/datasources/{source_id}/disable Authorization: Bearer ``` ### Test Data Source ```http POST /api/v1/datasources/{source_id}/test Authorization: Bearer Response (200 OK) { "status": "success", "data_count": 150, "execution_time_ms": 1250 } ``` ### Get Data Source Logs ```http GET /api/v1/datasources/{source_id}/logs Authorization: Bearer Query Parameters: - page: int - page_size: int - status: string (success, failed, running) - start_date: datetime - end_date: datetime ``` --- ## Tasks ### List Tasks ```http GET /api/v1/tasks Authorization: Bearer Query Parameters: - datasource_id: int - status: string - start_date: datetime - end_date: datetime ``` **Response (200 OK)** ```json { "total": 156, "data": [ { "id": 1234, "datasource_id": 1, "datasource_name": "TOP500", "status": "success", "started_at": "2024-01-20T08:00:00Z", "completed_at": "2024-01-20T08:01:15Z", "records_processed": 500, "error_message": null } ] } ``` ### Get Task ```http GET /api/v1/tasks/{task_id} Authorization: Bearer ``` ### Trigger Manual Run ```http POST /api/v1/datasources/{source_id}/trigger Authorization: Bearer Response (202 Accepted) { "task_id": 1567, "message": "Task queued successfully" } ``` ### Cancel Running Task ```http POST /api/v1/tasks/{task_id}/cancel Authorization: Bearer ``` --- ## Dashboard Data ### Overview Stats ```http GET /api/v1/dashboard/stats Authorization: Bearer ``` **Response (200 OK)** ```json { "total_datasources": 9, "active_datasources": 8, "tasks_today": 45, "success_rate": 97.8, "last_updated": "2024-01-20T10:30:00Z", "alerts": { "critical": 0, "warning": 2, "info": 5 } } ``` ### Data Summary by Module ```http GET /api/v1/dashboard/summary Authorization: Bearer ``` **Response (200 OK)** ```json { "L1": { "datasources": 5, "total_records": 12500, "last_updated": "2024-01-20T10:00:00Z" }, "L2": { "datasources": 4, "total_records": 8300, "last_updated": "2024-01-20T09:45:00Z" } } ``` ### Recent Activity ```http GET /api/v1/dashboard/activity Authorization: Bearer Query Parameters: - limit: int (default: 20) ``` --- ## GPU Clusters (L1 Data) ### List GPU Clusters ```http GET /api/v1/data/gpu-clusters Authorization: Bearer Query Parameters: - country: string - min_gpu_count: int - order_by: string (gpu_count, flops, rank) - order: string (asc, desc) - page: int - page_size: int ``` **Response (200 OK)** ```json { "total": 1500, "page": 1, "page_size": 50, "data": [ { "id": "epoch-gpu-001", "name": "Frontier", "country": "US", "city": "Oak Ridge, TN", "lat": 35.9327, "lng": -84.3107, "organization": "Oak Ridge National Laboratory", "gpu_count": 37888, "gpu_type": "AMD MI250X", "total_flops": 1.54e9, "rank": 1, "last_updated": "2024-01-15T00:00:00Z" } ] } ``` ### Get GPU Cluster Detail ```http GET /api/v1/data/gpu-clusters/{cluster_id} Authorization: Bearer ``` ### GPU Cluster Statistics ```http GET /api/v1/data/gpu-clusters/stats Authorization: Bearer ``` **Response (200 OK)** ```json { "total_clusters": 1500, "total_gpu_count": 2500000, "by_country": { "US": {"count": 800, "gpu_share": 0.45}, "CN": {"count": 350, "gpu_share": 0.20}, "EU": {"count": 200, "gpu_share": 0.15} }, "top_10_clusters": [...] } ``` --- ## Submarine Cables (L2 Data) ### List Submarine Cables ```http GET /api/v1/data/submarine-cables Authorization: Bearer Query Parameters: - status: string (active, planned, decommissioned) - country: string ``` **Response (200 OK)** ```json { "total": 436, "data": [ { "id": "cable-001", "name": "FASTER", "length_km": 11600, "owners": ["Google", "中国移动", "NEC"], "capacity_tbps": 60, "status": "active", "landing_points": [ {"country": "US", "city": "San Francisco", "lat": 37.7749, "lng": -122.4194}, {"country": "JP", "city": "Tokyo", "lat": 35.6762, "lng": 139.6503} ] } ] } ``` --- ## IXP Nodes (L2 Data) ### List IXPs ```http GET /api/v1/data/ixps Authorization: Bearer Query Parameters: - country: string - region: string ``` **Response (200 OK)** ```json { "total": 1200, "data": [ { "id": "ixp-001", "name": "Equinix Ashburn", "country": "US", "city": "Ashburn, VA", "member_count": 250, "traffic_tbps": 15.5, "ixp_db_id": "EQ-AS1" } ] } ``` --- ## Alerts ### List Alerts ```http GET /api/v1/alerts Authorization: Bearer Query Parameters: - severity: string (critical, warning, info) - status: string (active, acknowledged, resolved) - datasource_id: int ``` **Response (200 OK)** ```json { "total": 12, "data": [ { "id": 1, "severity": "warning", "datasource_id": 2, "datasource_name": "Epoch AI", "message": "API response time > 30s", "status": "active", "created_at": "2024-01-20T09:30:00Z", "acknowledged_by": null } ] } ``` ### Acknowledge Alert ```http POST /api/v1/alerts/{alert_id}/acknowledge Authorization: Bearer ``` ### Resolve Alert ```http POST /api/v1/alerts/{alert_id}/resolve Authorization: Bearer Content-Type: application/json { "resolution": "API rate limit adjusted" } ``` ### Alert Rules Configuration ```http GET /api/v1/alerts/rules POST /api/v1/alerts/rules PUT /api/v1/alerts/rules/{rule_id} DELETE /api/v1/alerts/rules/{rule_id} Authorization: Bearer ``` --- ## System Configuration ### Get Config ```http GET /api/v1/config Authorization: Bearer (admin only) ``` ### Update Config ```http PUT /api/v1/config Authorization: Bearer (admin only) Content-Type: application/json { "data_retention_days": 30, "refresh_interval": 300, "timezone": "Asia/Shanghai" } ``` --- ## Audit Logs ### List Audit Logs ```http GET /api/v1/audit-logs Authorization: Bearer (admin only) Query Parameters: - user_id: int - action: string - resource: string - start_date: datetime - end_date: datetime - page: int - page_size: int ``` **Response (200 OK)** ```json { "total": 1500, "data": [ { "id": 10001, "user_id": 1, "username": "admin", "action": "user.update", "resource": "users", "resource_id": 5, "detail": {"changes": {"role": ["viewer", "operator"]}}, "ip_address": "192.168.1.100", "created_at": "2024-01-20T10:30:00Z" } ] } ``` --- ## Health Check ### System Health ```http GET /health ``` **Response (200 OK)** ```json { "status": "healthy", "version": "1.0.0", "uptime_seconds": 86400, "components": { "database": "healthy", "redis": "healthy", "celery": "healthy" } } ``` ### Readiness ```http GET /ready ``` **Response (200 OK)** ```json { "ready": true } ``` --- ## Error Codes | Code | Description | |------|-------------| | 400 | Bad Request - Invalid input | | 401 | Unauthorized - Invalid/missing token | | 403 | Forbidden - Insufficient permissions | | 404 | Not Found - Resource doesn't exist | | 422 | Validation Error - Data validation failed | | 429 | Rate Limited - Too many requests | | 500 | Internal Server Error | | 503 | Service Unavailable |