photoncloud-monorepo/docs/por/T050-rest-api/task.yaml

id: T050
name: REST API - 全サービスHTTP API追加
goal: Add REST/HTTP APIs to all PhotonCloud services for curl accessibility in embedded/simple environments
status: active
priority: P1
owner: peerA
created: 2025-12-12
depends_on: []
blocks: []

context: |
  **User Direction (2025-12-12):**
  "全サービスについてREST APIを追加する想定（組み込みなどの環境で、curlで簡単に使えるように）"

  **Rationale:**
  - curl/wget で簡単にアクセス可能
  - 組み込み環境やシェルスクリプトで使いやすい
  - デバッグ・トラブルシューティングが容易
  - gRPC tooling不要

  **Current State:**
  - HTTP API あり: NightLight (Prometheus), LightningSTOR (S3 - T047)
  - gRPC のみ: ChainFire, FlareDB, IAM, PlasmaVMC, k8shost, PrismNET, etc.

acceptance:
  - All services have REST API alongside gRPC
  - curl examples documented for each endpoint
  - JSON request/response format
  - Consistent error response format across services
  - OpenAPI/Swagger spec generated (optional but recommended)

steps:
  - step: S1
    name: REST API Pattern Design
    done: Define consistent REST patterns across all services
    status: complete
    completed: 2025-12-12 01:42 JST
    owner: peerA
    priority: P0
    outputs:
      - path: specifications/rest-api-patterns.md
        note: Comprehensive REST API patterns (URL structure, error format, auth, curl examples)
    notes: |
      **COMPLETE (2025-12-12 01:42 JST)**

      Design decisions documented in specifications/rest-api-patterns.md:
      - URL structure: /api/v1/{resource}[/{id}][/{action}]
      - HTTP methods: GET/POST/PUT/DELETE mapping
      - Error response: {"error": {"code": "...", "message": "..."}, "meta": {...}}
      - Auth header: Authorization: Bearer <token>
      - Content-Type: application/json
      - Port convention: HTTP ports 8081-8091 (alongside gRPC 50051-50061)
      - Service-specific endpoints defined for all 11 services
      - curl examples provided
      - axum implementation notes

  - step: S2
    name: ChainFire REST API
    done: HTTP endpoints for KV operations
    status: pending
    owner: peerB
    priority: P0
    notes: |
      Endpoints:
      - GET /api/v1/kv/{key} - Get value
      - PUT /api/v1/kv/{key} - Put value (body: {"value": "..."})
      - DELETE /api/v1/kv/{key} - Delete key
      - GET /api/v1/kv?prefix={prefix} - Range scan
      - GET /api/v1/cluster/status - Cluster health
      - POST /api/v1/cluster/members - Add member

  - step: S3
    name: FlareDB REST API
    done: HTTP endpoints for DB operations
    status: pending
    owner: peerB
    priority: P0
    notes: |
      Endpoints:
      - POST /api/v1/sql - Execute SQL query (body: {"query": "SELECT ..."})
      - GET /api/v1/tables - List tables
      - GET /api/v1/kv/{key} - KV get
      - PUT /api/v1/kv/{key} - KV put
      - GET /api/v1/scan?start={}&end={} - Range scan

  - step: S4
    name: IAM REST API
    done: HTTP endpoints for auth operations
    status: pending
    owner: peerB
    priority: P0
    notes: |
      Endpoints:
      - POST /api/v1/auth/token - Get token (body: {"username": "...", "password": "..."})
      - POST /api/v1/auth/verify - Verify token
      - GET /api/v1/users - List users
      - POST /api/v1/users - Create user
      - GET /api/v1/projects - List projects
      - POST /api/v1/projects - Create project

  - step: S5
    name: PlasmaVMC REST API
    done: HTTP endpoints for VM management
    status: pending
    owner: peerB
    priority: P0
    notes: |
      Endpoints:
      - GET /api/v1/vms - List VMs
      - POST /api/v1/vms - Create VM
      - GET /api/v1/vms/{id} - Get VM details
      - DELETE /api/v1/vms/{id} - Delete VM
      - POST /api/v1/vms/{id}/start - Start VM
      - POST /api/v1/vms/{id}/stop - Stop VM

  - step: S6
    name: k8shost REST API
    done: HTTP endpoints for K8s operations
    status: pending
    owner: peerB
    priority: P1
    notes: |
      Endpoints:
      - GET /api/v1/pods - List pods
      - POST /api/v1/pods - Create pod
      - DELETE /api/v1/pods/{name} - Delete pod
      - GET /api/v1/services - List services
      - POST /api/v1/services - Create service

  - step: S7
    name: CreditService REST API
    done: HTTP endpoints for credit/quota
    status: pending
    owner: peerB
    priority: P1
    notes: |
      Endpoints:
      - GET /api/v1/wallets/{project_id} - Get wallet balance
      - POST /api/v1/wallets/{project_id}/reserve - Reserve credits
      - POST /api/v1/wallets/{project_id}/commit - Commit reservation

  - step: S8
    name: PrismNET REST API
    done: HTTP endpoints for network management
    status: pending
    owner: peerB
    priority: P1
    notes: |
      Endpoints:
      - GET /api/v1/vpcs - List VPCs
      - POST /api/v1/vpcs - Create VPC
      - GET /api/v1/subnets - List subnets
      - POST /api/v1/ports - Create port

  - step: S9
    name: Documentation & Examples
    done: curl examples and OpenAPI spec
    status: pending
    owner: peerB
    priority: P1
    notes: |
      Deliverables:
      - docs/api/rest-api-guide.md with curl examples
      - OpenAPI spec per service (optional)
      - Postman collection (optional)

evidence: []
notes: |
  **Implementation Approach:**
  - Use axum (already in most services) for HTTP handlers
  - Run HTTP server alongside gRPC on different port (e.g., gRPC:50051, HTTP:8080)
  - Share business logic between gRPC and HTTP handlers

  **Port Convention:**
  - gRPC: 50051-50060
  - HTTP: 8081-8090 (service-specific)

  **Synergy with T048 (SDK):**
  - REST API enables simpler client implementations
  - Can generate SDK from OpenAPI if we choose to

  **Execution Note:**
  - Can parallelize S2-S8 across multiple services
  - S1 (pattern design) must complete first