Http Api — HTTP/JSON API 设计与审查

### HTTP API 设计和审查 **HTTP 接口 API**（通常为 JSON）：可预测的 URL、诚实的状态码和客户端可以构建的错误——**无需** 复制 **api-compat** 技能中关于长期版本控制策略的所有内容。 ## 范围 - **建模**：名词/资源、集合、当 RPC 风格比假 REST 更清晰时的操作。 - **HTTP 语义**：哪些方法、**幂等性**、当相关时的缓存头。 - **错误**：稳定的机器可读代码、关联 ID、避免泄露内部信息。 - **开发者体验**：示例、OpenAPI 片段、一致的分页/过滤模式。 ## 不在范围内（交付） - **OAuth/OIDC** 协议细节 → 身份专用技能。 - **GraphQL-only** 模式设计 → graphql-schema 技能。 - **多年弃用策略** 和客户迁移程序 → 配对使用 **api-compat**。 ## 审查顺序 1. **读路径** — 客户端是否可以在不猜测的情况下导航域？ 2. **写安全** — 重试安全？ 处理重复提交？ 3. **错误** — 一致的形状； 4xx vs 5xx 诚实。 4. **演进** — 文档中什么会变化 vs 什么是稳定的（兼容细节在 api-compat 中）。 ## 设计陷阱 - 状态 200 与 `{error: ...}`； **每个** POST 返回 200； 无限列表端点； 错误体中包含秘密。 ## 完成条件 - 新工程师可以仅凭文档调用 API； 失败案例是 **可测试** 和 **一致** 的。