linkong/planet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d18e400fcb77f72636ed2929634290ceef991f97
planet/api_design.md
rayd1o e7033775d8 first commit
2026-03-05 11:46:58 +08:00

12 KiB
Raw Blame History

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

POST /api/v1/auth/login
Content-Type: application/json

{
    "username": "admin",
    "password": "admin123"
}

Response (200 OK)

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "bearer",
    "expires_in": 900,
    "user": {
        "id": 1,
        "username": "admin",
        "role": "super_admin"
    }
}

Response (401 Unauthorized)

{
    "detail": "Invalid credentials"
}

Refresh Token

POST /api/v1/auth/refresh
Authorization: Bearer <refresh_token>

Response (200 OK)

{
    "access_token": "new_access_token",
    "expires_in": 900
}

Logout

POST /api/v1/auth/logout
Authorization: Bearer <access_token>

Get Current User

GET /api/v1/auth/me
Authorization: Bearer <access_token>

Response (200 OK)

{
    "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

GET /api/v1/users
Authorization: Bearer <token>

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)

{
    "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

GET /api/v1/users/{user_id}
Authorization: Bearer <token>

Create User

POST /api/v1/users
Authorization: Bearer <token>
Content-Type: application/json

{
    "username": "newuser",
    "email": "newuser@example.com",
    "password": "securepassword123",
    "role": "operator"
}

Response (201 Created)

{
    "id": 46,
    "username": "newuser",
    "email": "newuser@example.com",
    "role": "operator",
    "is_active": true,
    "created_at": "2024-01-20T10:00:00Z"
}

Update User

PUT /api/v1/users/{user_id}
Authorization: Bearer <token>
Content-Type: application/json

{
    "email": "updated@example.com",
    "role": "admin",
    "is_active": true
}

Delete User

DELETE /api/v1/users/{user_id}
Authorization: Bearer <token>

Change Password

POST /api/v1/users/{user_id}/change-password
Authorization: Bearer <token>
Content-Type: application/json

{
    "old_password": "oldpassword",
    "new_password": "newpassword123"
}

Data Sources

List Data Sources

GET /api/v1/datasources
Authorization: Bearer <token>

Query Parameters:
- module: string (L1, L2, L3, L4)
- is_active: boolean
- priority: string (P0, P1)

Response (200 OK)

{
    "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

GET /api/v1/datasources/{source_id}
Authorization: Bearer <token>

Create Data Source

POST /api/v1/datasources
Authorization: Bearer <token>
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

PUT /api/v1/datasources/{source_id}
Authorization: Bearer <token>
Content-Type: application/json

{
    "frequency": "30m",
    "is_active": true
}

Enable/Disable Data Source

POST /api/v1/datasources/{source_id}/enable
POST /api/v1/datasources/{source_id}/disable
Authorization: Bearer <token>

Test Data Source

POST /api/v1/datasources/{source_id}/test
Authorization: Bearer <token>

Response (200 OK)
{
    "status": "success",
    "data_count": 150,
    "execution_time_ms": 1250
}

Get Data Source Logs

GET /api/v1/datasources/{source_id}/logs
Authorization: Bearer <token>

Query Parameters:
- page: int
- page_size: int
- status: string (success, failed, running)
- start_date: datetime
- end_date: datetime

Tasks

List Tasks

GET /api/v1/tasks
Authorization: Bearer <token>

Query Parameters:
- datasource_id: int
- status: string
- start_date: datetime
- end_date: datetime

Response (200 OK)

{
    "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

GET /api/v1/tasks/{task_id}
Authorization: Bearer <token>

Trigger Manual Run

POST /api/v1/datasources/{source_id}/trigger
Authorization: Bearer <token>

Response (202 Accepted)
{
    "task_id": 1567,
    "message": "Task queued successfully"
}

Cancel Running Task

POST /api/v1/tasks/{task_id}/cancel
Authorization: Bearer <token>

Dashboard Data

Overview Stats

GET /api/v1/dashboard/stats
Authorization: Bearer <token>

Response (200 OK)

{
    "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

GET /api/v1/dashboard/summary
Authorization: Bearer <token>

Response (200 OK)

{
    "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

GET /api/v1/dashboard/activity
Authorization: Bearer <token>

Query Parameters:
- limit: int (default: 20)

GPU Clusters (L1 Data)

List GPU Clusters

GET /api/v1/data/gpu-clusters
Authorization: Bearer <token>

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)

{
    "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

GET /api/v1/data/gpu-clusters/{cluster_id}
Authorization: Bearer <token>

GPU Cluster Statistics

GET /api/v1/data/gpu-clusters/stats
Authorization: Bearer <token>

Response (200 OK)

{
    "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

GET /api/v1/data/submarine-cables
Authorization: Bearer <token>

Query Parameters:
- status: string (active, planned, decommissioned)
- country: string

Response (200 OK)

{
    "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

GET /api/v1/data/ixps
Authorization: Bearer <token>

Query Parameters:
- country: string
- region: string

Response (200 OK)

{
    "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

GET /api/v1/alerts
Authorization: Bearer <token>

Query Parameters:
- severity: string (critical, warning, info)
- status: string (active, acknowledged, resolved)
- datasource_id: int

Response (200 OK)

{
    "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

POST /api/v1/alerts/{alert_id}/acknowledge
Authorization: Bearer <token>

Resolve Alert

POST /api/v1/alerts/{alert_id}/resolve
Authorization: Bearer <token>
Content-Type: application/json

{
    "resolution": "API rate limit adjusted"
}

Alert Rules Configuration

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 <token>

System Configuration

Get Config

GET /api/v1/config
Authorization: Bearer <token> (admin only)

Update Config

PUT /api/v1/config
Authorization: Bearer <token> (admin only)
Content-Type: application/json

{
    "data_retention_days": 30,
    "refresh_interval": 300,
    "timezone": "Asia/Shanghai"
}

Audit Logs

List Audit Logs

GET /api/v1/audit-logs
Authorization: Bearer <token> (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)

{
    "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

GET /health

Response (200 OK)

{
    "status": "healthy",
    "version": "1.0.0",
    "uptime_seconds": 86400,
    "components": {
        "database": "healthy",
        "redis": "healthy",
        "celery": "healthy"
    }
}

Readiness

GET /ready

Response (200 OK)

{
    "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
Reference in New Issue View Git Blame Copy Permalink