文档开发者接入

业务 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 表示已受理,不是完成。

http
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;最终状态由持久化结果确认。

json
{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "detail": "The idempotency key was used with a different payload.",
  "code": "IDEMPOTENCY_CONFLICT",
  "requestId": "rq_example"
}

正式开放的验收条件

需提供机器可读接口定义、身份与租户测试、限流参数、幂等窗口、异步超时语义、兼容政策和运维负责人。联调覆盖跨组织拒绝、无权限资源、重复请求、断线后查状态及旧版本兼容。未提供这些条件前,本页用于方案讨论,不作为可用 API 承诺。

返回全部文档下一篇指南

还有疑问?

查看专家支持