业务 API 开放协议草案 v0.1
定义资源、身份、分页、异步任务、幂等与错误结构,供接入评审。
草案范围与启用前提
本草案提出面向第三方的业务资源协议,不把客户端内部接口作为稳定公共 API。接入前需落实服务地址、认证发行、租户隔离、权限校验、限流、日志和测试环境,并形成正式接口版本。下述路径、scope 和字段均为拟议契约。
身份、组织与最小权限
建议为应用发行可撤销、可过期的服务身份,按组织和项目绑定 scope,例如 projects:read、task-requests:create。每次请求同时验证身份、资源归属和操作权限,不信任请求里的 companyId。密钥保存在服务端,禁止放在浏览器包或应用 manifest。具体 OAuth / 服务令牌方案需在正式开放前确定。
建议的最小资源面
首批资源以查询和提交待评审请求为主。提交请求不表示工作已执行,也不绕过人工审批;审批动作及高风险工具操作暂不纳入这份草案。
| 方法与路径 | 语义 | 拟议 scope |
|---|---|---|
| GET /v1/projects | 查询授权项目,游标分页 | projects:read |
| POST /v1/task-requests | 创建待处理请求,返回 202 和标识 | task-requests:create |
| GET /v1/task-requests/{id} | 读取请求状态、结果引用和失败原因 | task-requests:read |
请求与异步结果示例
使用 UTF-8 JSON、带时区的 ISO 8601 时间和不透明资源标识。引用资料只允许指向已授权资源,不接受任意内网 URL。以下请求只描述需求和验收标准;HTTP 202 表示已受理,不是完成。
POST /v1/task-requests HTTP/1.1
Authorization: Bearer SCOPED_SERVICE_TOKEN
Content-Type: application/json
Idempotency-Key: req-20261116-report-001
{
"projectId": "prj_example",
"objective": "Prepare a read-only weekly report",
"sourceRefs": ["source_example"],
"acceptance": "Totals reconcile; cite source records"
}
HTTP/1.1 202 Accepted
Location: /v1/task-requests/tr_example
Content-Type: application/json
{"id":"tr_example","status":"accepted","requestId":"rq_example"}分页、限流与幂等
列表建议返回 items 与 nextCursor,limit 默认 50、最大 100;这些数值待实现确认。写请求按服务身份、组织、路由和 Idempotency-Key 去重;相同键不同内容返回冲突,去重保留窗口须正式公布。客户端对 429 和可重试故障采用有限退避,并尊重 Retry-After。超时后先查询请求状态,不生成新键重复提交。
错误、状态与可观测性
错误建议采用 RFC 9457 的 application/problem+json,扩展稳定 code 和 requestId,避免泄露凭据、内部路径或他人资源。区分 400 输入错误、401 无有效身份、403 权限不足、404 不可见资源、409 冲突、429 限流和 5xx 故障。任务状态可为 accepted、running、awaiting_review、succeeded、failed、cancelled;最终状态由持久化结果确认。
{
"type": "about:blank",
"title": "Conflict",
"status": 409,
"detail": "The idempotency key was used with a different payload.",
"code": "IDEMPOTENCY_CONFLICT",
"requestId": "rq_example"
}正式开放的验收条件
需提供机器可读接口定义、身份与租户测试、限流参数、幂等窗口、异步超时语义、兼容政策和运维负责人。联调覆盖跨组织拒绝、无权限资源、重复请求、断线后查状态及旧版本兼容。未提供这些条件前,本页用于方案讨论,不作为可用 API 承诺。