该技能用于指导 REST API 的设计、版本管理与文档编写，适用场景包括设计新接口、在 REST、GraphQL 与 gRPC 之间选型，以及实现 API 等。
核心原则是 REST 优先、以 OpenAPI 为驱动、默认保持向后兼容。资源用名词表示，HTTP 方法作动词：GET 用于列表或获取单个资源，POST 创建，PUT 替换，PATCH 更新，DELETE 删除；关联资源通过 URL 层级表达，如 GET /users/123/orders。应避免 /getUser、/createOrder 这类 RPC 风格路径。
状态码约定：200 用于成功的 GET、PUT、PATCH，201 用于成功创建，204 用于无响应体的删除，400 请求格式错误，401 未认证，403 未授权，404 资源不存在，409 业务冲突，422 校验失败，500 服务端错误。
错误响应采用统一结构，包含 error.code、error.message 与 error.details，details 中逐字段给出 field、message、value。
分页通过查询参数实现，如 ?page=2&per_page=50&sort=created_at&order=desc，响应包含 data 与 meta，meta 内有 page、per_page、total、total_pages。
版本管理对公开 API 使用 URL 版本号（/v1/users、/v2/users）；仅破坏性变更才升主版本，至少提前 6 个月弃用通知，过渡期并行支持旧版本，增量变更不需新版本。
推荐先写 OpenAPI 3.0.0 规范再实现代码。需避免的反模式包括 RPC 风格端点、全部用 POST、过深嵌套、错误格式不一致、未升版本即破坏兼容、文档与实现不符。资料未提供具体安装命令、许可与收费信息。