调用约定
理解版本化路径、响应封装、分页、幂等和异步任务。
URL 与请求
使用平台提供的同源 HTTPS 入口,管理接口常用 /api/v1/,认证接口为 /api/auth/v1/,部分平台管理接口位于 /api/admin/v1/。各方法和路径以参考页为准。
JSON 写请求设置 Content-Type: application/json。未定义字段可能被拒绝,不在请求中追加内部主机地址、文件路径或其他契约未声明字段。
响应
常见 JSON 封装为 data 与 request_id,错误为 error 与 request_id。健康检查、文件下载和特殊通道可能不同,应按单接口的响应媒体类型处理。
{
"data": {"id": "<任务 UUID>", "resource_id": "<资源 UUID>", "state": "queued"},
"request_id": "<请求标识>"
}该示例表示任务已受理,不表示资源已创建。data.id 在不同接口可能是任务或资源身份,必须按具体操作语义解释。
分页与范围
只对声明分页参数的接口发送 page、page_size,不要假定所有列表有同一封装或默认大小。显式租户参数不能替代授权;当前工作区、默认租户和关联资源归属见租户上下文。
其他约定
- 资源身份使用 UUID,名称用于显示,不解析名称生成资源路径。
- 容量字段如
size_gib以 GiB 表示,时间按契约的 date-time 处理。 - 支持的写操作使用
Idempotency-Key,同次业务重试保留原键和参数。 - HTTP 200 的任务响应继续轮询任务;文件下载按响应类型保存,不强行解析 JSON。
- API 参考的 JSON 结构是字段定义,不是可以直接提交的业务示例。
