restful-api-design

Web API 设计

一项从语义、兼容性和可运维性角度判断 Web API 表层设计的技能。

HTTP 不只是传输通道。只要不破坏方法、状态码、缓存、条件请求、表示形式等既有语义，API 就会更易于理解、修改，也更不易出错。

---

何时使用此技能

• 设计新 API 的端点
• 重新审视现有 API 的 URL / HTTP 方法 / 响应结构
• 决定分页、筛选、排序和搜索的设计方针
• 整理错误格式和状态码的一致性
• 决定破坏性变更、版本管理和兼容性维护方针
• 在 API 评审中判断表层设计是否合理

此技能不涵盖的内容

• 模块边界或内部职责划分
• 数据库架构设计本身
• SDK 的特定语言实现细节
• API 网关或基础设施产品的配置细节

如果主题是内部结构的职责分离，请优先使用 module-boundary-design。

---

依据的优先级

设计决策的依据按以下优先级处理。低优先级依据与高优先级依据冲突时，始终以高优先级为准。

1. RFC 中定义的 HTTP / URI / MIME / Problem Details 等规范
2. WHATWG、W3C、IANA 等 Web 标准规范、注册表和互操作规则
3. MDN 等面向实践整理标准规范内容的公开文档
4. RFC 和 Web 标准无法明确唯一决定的事项中，以可维护性和可运维性为优先的组织默认值

---

输出格式

使用此技能设计或评审 API 时，请输出以下成果：

1. 资源列表：名词、属于 collection 还是 item、父子关系
2. 端点表：method、path、目的、request 要点、response 要点、主要 status
3. 错误格式：符合 Problem Details 的示例（type、title、status、detail、instance）
4. 列表获取策略：page size / cursor / filter / sort / fields 的默认值
5. 幂等性与重试设计：是否需要 idempotency key、重新发送时的注意事项
6. 缓存与并发：是否采用 ETag / If-Match、异步操作的跟踪方式
7. 兼容性与版本管理：破坏性变更的定义、version strategy
8. 待解问题 / 风险：未决事项、注意点

---

基本原则

1. 从语义出发设计

首先要确定的不是 URL 或 JSON，而是客户端想做什么，以及为此需要怎样的状态转换。

• 哪些名词是 API 的核心
• 这些名词属于 collection 还是 item
• 客户端要观察或操作哪些状态
• 哪些转换可以用标准方法表示

如果只先构建表层设计，就会变成数据库架构或内部实现需求的映射。

2. 不破坏 HTTP 的语义

HTTP 方法和状态码已有其含义。不要用自定义规则覆盖这些含义。关于方法和状态码的具体分配，请参阅 references/http-semantics.md。

3. 一致性优先于易用性

即使短期内更方便，例外规则不断增加的 API 也会在中长期逐渐崩坏。相比单个便利案例，应优先保证整体一致性。

---

HTTP 语义与设计流程详解

如需了解资源定义、URL、表示形式、HTTP 方法、状态码、错误格式、列表获取、幂等性、缓存、版本管理和安全方面的具体决策（包括 Step 1〜11、方法表和状态码表），请阅读 references/http-semantics.md。

---

默认值列表

除非有明确理由，否则采用以下默认值。

项目	默认值
URL 风格	noun-based, kebab-case
列表获取	GET /resources
详情获取	GET /resources/{id}
创建	POST /resources
部分更新	PATCH /resources/{id}
全量替换	PUT /resources/{id}
删除	DELETE /resources/{id}
错误格式	RFC 9457 Problem Details (application/problem+json)
pagination	统一使用 page_size + page_token 或 limit + cursor
field/query 大小写	在整个 API 中统一（默认：snake_case）
PATCH media type	确定团队默认值（application/merge-patch+json 或 application/json）
破坏性变更	新 major version
异步处理	202 Accepted + operation resource（Location 标头）

---

反模式

• 将数据库表名直接用作 API 名称
• 使用 /getX、/createX、/searchX 等动词密集型 URL
• 所有读取请求都通过 POST 接收
• 将成功和失败都包装为 200
• 仅用面向人类的消息表示错误类型
• 返回无限量的列表
• 在 page token 中暴露内部 offset 或机密信息
• 混淆 PATCH 和 PUT 的含义
• 处理异步操作，却不提供 202 和跟踪方式
• 不添加 field，只改变现有 field 的含义

---

最终检查

设计完成时请确认以下内容。全部为 Yes，即表示至少达到了基本要求。

• 资源名称是否为稳定的名词，URL 中是否没有暴露动词或实现细节
• 是否没有破坏 HTTP 方法的语义（GET 是安全的，PUT 是全量替换，PATCH 是部分更新）
• 状态码是否与结果一致，401/403/404 的区分是否统一
• 错误是否采用 RFC 9457 Problem Details 格式且机器可读
• 是否已为列表获取设计 pagination / filter / sort
• 是否已整理 retry / idempotency 的前提，并采取措施防止重复创建或重复扣费
• 异步处理是否提供 202 + 跟踪方式（操作状态 endpoint / Location）
• 是否已针对需要的场景考虑条件更新（If-Match / ETag）
• 破坏性变更和 version policy 是否明确
• 身份验证、授权和机密信息的处理是否统一，token/secret 是否没有暴露在 URL 中
• 是否能够说明资源和操作的含义，并在未来变更时判断“哪些属于破坏性变更”

---

参考资料

• 设计流程详解（Step 1〜11、方法表和状态码表）：references/http-semantics.md
• RFC 9110：HTTP 语义
• RFC 9111：HTTP 缓存
• RFC 9457：HTTP API 的 Problem Details
• RFC 6750：Bearer Token 用法
• RFC 5789 / 6902 / 7396：PATCH 与 JSON patch 系列
• MDN Web Docs：关于 HTTP / Web API 的公开文档

---

プロジェクト既定値の優先

## 既定値一覧 に挙げた既定値は、RFC や Web 標準だけでは一意に決まらない箇所での汎用的な出発点にすぎない。次の項目は、対象プロジェクトの CLAUDE.md / AGENTS.md・API 契約ドキュメント（OpenAPI 定義や API ガイドライン）に既定が定義されている場合、このスキルの既定値より常にそちらを優先する。

• ページネーションのパラメータ名: page_size / limit・page_token / cursor のどちらを採用し、どう命名するか。プロジェクトの既存 API で採用済みの名前があれば、それに合わせて統一する。
• PATCH の media type: application/merge-patch+json と独自 application/json のどちらを既定とするか。
• 互換性・バージョニングポリシー: 破壊的変更の定義、version の表現方法、移行期間の扱い。

プロジェクト側の既定が存在し、このスキルの既定値と衝突する場合は、迷わずプロジェクト側に従う。プロジェクト側に定義がないときに限り ## 既定値一覧 を出発点とし、採用した既定を成果物（open questions / リスク）に明示する。