Skip to content

api-contract.md

Latest commit

 

History

History
209 lines (156 loc) · 4.12 KB

api-contract.md

File metadata and controls

209 lines (156 loc) · 4.12 KB

Compute Tide Frontend API Contract

This project has moved from the prototype snapshot API to the formal V1 domain API described by the PRD/TDD. The old /api/compute-tide/* mock endpoints are still kept for legacy demos, but the Vue frontend now calls the formal /api/* endpoints in remote mode.

Data Source Modes

  • mock: use local Pinia mock data, no network required.
  • remote: call the configured backend Base URL with formal V1 API paths.

Default remote Base URL in the frontend:

http://127.0.0.1:8787

The local mock-server.js now implements both:

  • legacy prototype API: /api/compute-tide/*
  • formal V1 API: /api/*

Unified Response

Formal APIs return:

{
  "code": "0",
  "message": "success",
  "data": {}
}

Error responses should use non-zero code and a user-readable message.

Formal Endpoints

Auth

GET /api/auth/me

Returns the current user and role.

Bootstrap

GET /api/bootstrap

Returns a full frontend bootstrap payload:

{
  "resourcePools": [],
  "nodes": [],
  "applications": [],
  "approvalTodos": [],
  "tasks": [],
  "compliance": [],
  "migrations": [],
  "messages": []
}

Monitor

GET /api/monitor/usage
GET /api/monitor/reservation

V1 usage monitor only promises GPU occupied cards and GPU occupancy rate inferred from task snapshots. It does not promise real GPU utilization, CPU utilization, or memory utilization.

Applications

GET  /api/applications
POST /api/applications
GET  /api/applications/{applyId}
POST /api/applications/{applyId}/cancel
POST /api/applications/{applyId}/change

Create request body:

{
  "poolCode": "training",
  "startTime": "2026-05-08 09:00",
  "endTime": "2026-05-08 12:00",
  "gpuCount": 4,
  "topologyType": "必须单节点",
  "purpose": "模型训练",
  "remark": "optional"
}

Application statuses:

  • 待审批
  • 审批中
  • 生效中
  • 已结束
  • 已取消
  • 已终止

Approvals

GET  /api/approvals/todos
GET  /api/approvals/{applyId}
POST /api/approvals/{applyId}/approve
POST /api/approvals/{applyId}/reject

Approval/reject body:

{
  "comment": "审批意见"
}

Approve may return business error NO_REMAINING_CAPACITY with message 已无剩余容量 when the remaining reservable capacity is not enough.

Reject comments are required by product rules.

Compliance

GET /api/compliance
GET /api/compliance/{applyId}
GET /api/anomalies

Compliance anomaly types:

  • 无申请ID
  • 申请ID无效
  • 超时使用
  • 超额使用
  • 完全未使用

Messages

GET  /api/messages
POST /api/messages/{id}/read
POST /api/messages/read-all

Message items include optional recipients: string[] for notification matrix audit display.

Migrations

GET  /api/migrations
POST /api/migrations
GET  /api/migrations/{migrationNo}

Create request body:

{
  "sourcePoolCode": "training",
  "targetPoolCode": "shared",
  "nodeList": ["node-a100-01"],
  "remark": "资源池容量调整",
  "riskSummary": "迁移后源/目标资源池容量均覆盖当前未来占用。"
}

V1 migration is an immediate manual operation. Risk warning does not block submission. Migration records include requestPayload, responsePayload, and optional riskSummary for audit display.

Admin

GET /api/admin/users
POST /api/admin/users
PUT /api/admin/users/{id}
POST /api/admin/users/{id}/reset-password
GET /api/admin/pools
PUT /api/admin/pools/{poolCode}
GET /api/admin/nodes
PUT /api/admin/nodes/{nodeName}
GET /api/admin/approval-flows/{poolId}
PUT /api/admin/approval-flows/{poolId}
GET /api/admin/configs
PUT /api/admin/configs/{key}

The frontend supports read/write mock admin views for users, pools, nodes, approval flows, and configs.

Legacy Prototype Endpoints

Kept for transition only:

GET  /api/compute-tide/bootstrap
POST /api/compute-tide/reservations
POST /api/compute-tide/reservations/{reservationId}/lifecycle
POST /api/compute-tide/nodes/{nodeId}/migrate
POST /api/compute-tide/reset

New frontend work should prefer the formal /api/* endpoints.