用途
本技能用于设计、实现与维护 RESTful API，重点解决 API 设计中的风格一致性与可扩展性问题。文档明确指出在以下场景应使用它：从零设计新的 RESTful API；构建带 HTTP/REST 接口的微服务；重构既有 API 以改善设计与一致性；按正确 HTTP 语义实现 CRUD；为已有 API 增加版本控制；设计资源关系与嵌套端点；实现分页、过滤与排序；统一错误与校验处理；构建超媒体驱动 API（HATEOAS）；通过缓存与压缩优化性能；使用 OpenAPI/Swagger 编写文档；通过认证与授权模式保障 API 安全。
核心 REST 原则
文档首先阐述 REST（表述性状态转移）作为分布式系统架构风格的核心特征：以资源为中心（每个资源有唯一 URI）、使用标准 HTTP 方法（GET、POST、PUT、DELETE、PATCH）、无状态（每个请求包含处理所需的全部信息）、客户端—服务器分离、可缓存、统一接口。随后介绍 Richardson 成熟度模型，将 API 设计分为四级：Level 0 单一 URI 单一方法（POX 沼泽）、Level 1 多资源 URI、Level 2 正确使用 HTTP 动词、Level 3 引入超媒体控制（HATEOAS），并给出各级的示例路径。
资源建模
在资源命名方面，文档给出四条约定并附带正反示例：使用名词而非动词（如 GET /users 而非 GET /getUsers）；集合使用复数名词（如 GET /users 与 GET /users/123）；使用小写与连字符（如 /user-profiles，而非驼峰或下划线）；层级表示关联资源（如 /users/123/posts）。同时提醒避免过深嵌套，建议最多 2 至 3 层，并给出过深嵌套的反例 /organizations/1/departments/2/teams/3/members/4/tasks/5。
文档列举五类资源设计模式：一是集合与单项资源模式，分别对应列表/创建与获取/替换/局部更新/删除；二是嵌套资源模式，用于父子关系（如 /posts/42/comments）；三是查询参数过滤集合（如按 category、price_min/price_max、sort/order、status/role 过滤）；四是资源上的动作（控制器）模式，用于不适合标准 CRUD 的操作（如 /users/123/activate、/orders/456/cancel、/payments/789/refund 等）；五是批量操作模式（如 /users/bulk-create、PATCH /products/bulk-update、DELETE /orders?ids=1,2,3,4,5）。
HTTP 方法
文档逐一深入说明五种方法。GET：安全、幂等、可缓存，给出 FastAPI 与 Express.js 的集合端点与单项端点示例，含分页参数（skip、limit）与 404 处理。POST：非安全、非幂等，创建成功应返回 201 并带 Location 头，示例展示 FastAPI 的 status_code=201 与响应头设置，以及 Express.js 中先校验必填字段再创建并设置 Location 的写法。PUT：非安全但幂等，用于整资源替换，要求所有字段必填，不存在时返回 404。PATCH：非安全但幂等，仅更新传入字段，FastAPI 示例使用 model_dump(exclude_unset=True) 获取部分字段。DELETE：非安全但幂等，可返回 204 No Content 或 200 OK 带响应体，文档分别给出两种写法的代码示例。
版本控制策略
文档目前展开两种策略。第一种是 URI 版本控制（最常见）：把版本放入路径，优点是可显式可见、易于路由到不同代码版本、对浏览器友好、便于文档化；缺点是产生多个端点、可能导致代码重复、URL 会随版本变化。给出 FastAPI 使用 APIRouter(prefix="/api/v1") 与 v2 路由并存并 include_router 的完整示例，以及 Express.js 用 express.Router() 挂载到 /api/v1 与 /api/v2 的示例，其中 v2 相比 v1 增加了分页与更多字段。第二种是请求头版本控制：通过自定义头（如 X-API-Version）或 Accept 头指定版本，优点是 URI 干净、不污染 URL、更符合 REST 单一 URI 理念；缺点是可见性差、浏览器测试困难、路由逻辑更复杂。文档给出 FastAPI 使用 Header(alias="X-API-Version") 按版本分支返回并在不支持时抛出 400 的示例，以及 Express.js 读取 req.get('X-API-Version') 的实现。
适用场景与限制
该技能最适合后端开发者、全栈开发者与需要统一 API 规范的技术团队，可在新项目 API 设计阶段作为选型与规范参考，也可用于既有接口的重构审查。示例以 FastAPI 和 Express.js 为主，其他语言或框架未在资料中给出对应示例。文档中提到的 HATEOAS、分页、过滤、错误处理、缓存压缩、OpenAPI 文档与安全模式虽在用途列表中列出，但其具体实现细节在现有资料中尚未完整展开；收费方式、价格与支持的平台类型暂未提供。