标识
Appaloft 的 HTTP API 基于 oRPC 构建,输入输出直接复用和 CLI、Web、SDK 相同的业务操作 Schema——文档描述的是字段含义,而不是为 HTTP 单独发明的另一套业务语义。
交互式文档入口
后端默认在以下地址提供机器可读和交互式文档:
| 地址 | 说明 |
|---|---|
/api/openapi.json | OpenAPI 3.1 规范文档 |
/api/reference | 基于 Scalar 的交互式 API Reference,可以直接在浏览器里试调用 |
/docs/reference/openapi/ | 公共文档站点生成的 OpenAPI Reference 入口,每个操作展开为独立页面 |
OpenAPI 操作会按 Appaloft 业务领域打上标签,因此 Scalar 和生成的文档不会退化成一个平铺的路由列表。这些入口由内置的 OpenAPI Reference 系统插件注册;如果需要把同一套文档嵌入到其他 Bun/Elysia 服务,可以 import @appaloft/openapi 并挂载它导出的 Response handler。
认证
| 场景 | 凭据类型 |
|---|---|
| 交互式产品操作(Web 会话) | 产品会话 Cookie |
| 机器自动化 / CI / Agent | Deploy Token(Bearer) |
curl https://appaloft.example/api/projects \
-H "Authorization: Bearer $APPALOFT_TOKEN"不要把 Deploy Token 写入仓库配置文件;在 CI 中应通过受信任的 Secret 或环境变量注入。
生命周期状态
部署、资源、证书等异步操作的状态应该通过公开的查询操作或读模型观察,而不是检查数据库或内部运行时对象:
curl https://appaloft.example/api/deployments/dep_123错误与恢复
错误响应包含稳定的 code、category、是否 retryable,以及相关的排障页面链接——完整字段说明见错误码与状态。
文档链接约定
OpenAPI、oRPC 和未来的工具描述都应该指向公共文档的稳定锚点,而不是内部 spec 文件路径,这样无论是从 Scalar、CLI --help 还是外部书签跳转,最终都会落到同一个可读页面。