用途
api-design 是一个用于设计生产级 REST API 的技能，属于 dev-skills-collection。它面向需要设计、审查或规范化 REST 接口的场景，内容涵盖资源命名、HTTP 语义、状态码、请求/响应设计、版本管理、OpenAPI 规范、认证、限流、错误处理、Webhook 与批量操作等主题。资料显示其触发方式为用户提出诸如“设计一个 REST API”“创建 API 端点”“编写 OpenAPI 规范”“设计 API”等请求。
主要能力
资料列出的能力包括：
- 资源命名：RESTful URI 约定与层级设计
- HTTP 方法映射：正确使用 GET、POST、PUT、PATCH、DELETE
- 状态码选择：为各种场景选择合适的代码
- 请求/响应设计：信封结构、分页、过滤、排序
- API 版本管理：URL、请求头、查询参数策略
- OpenAPI 规范：生成完整的 3.1 规范及示例
- 认证模式：API key、OAuth2、JWT Bearer token
- 限流：响应头、策略与客户端指引
- HATEOAS：超媒体驱动的 API 导航
- 错误处理：RFC 7807 Problem Details 格式
- Webhook 设计：事件驱动的 API 扩展模式
- 批量操作：批量端点与部分失败处理
- 幂等性：使用幂等键进行安全重试
使用方式
调用格式为：
/api-design [command] [options]
支持的命令包括：
- design <resource>：为一个资源设计 CRUD 端点
- openapi <resource>：为一个资源生成 OpenAPI 3.1 规范
- endpoints <domain>：为一个领域提出端点结构
- review <spec>：按最佳实践审查现有 API 设计
- paginate <strategy>：实现游标或偏移分页
- errors：生成 RFC 7807 错误响应模板
- webhooks <events>：为给定事件设计 Webhook 端点
- version <strategy>：将版本策略应用到现有 API
API 版本管理策略
资料给出四种策略：URL 路径（推荐，简单可见，易于路由，但不够纯粹 RESTful）、自定义请求头（URL 干净，但隐藏且不易在浏览器测试）、Accept 请求头内容协商（RESTful 纯粹，但复杂且工具支持差）、查询参数（易于测试，但污染查询字符串，容易遗忘）。
认证模式
包括 API key 认证（建议放在请求头中，使用前缀区分类型、存储时哈希、支持轮换、仅在创建时返回完整密钥）、OAuth 2.0 Bearer Token，以及 JWT 结构示例和 Token 刷新模式。
限流
资料给出了响应头示例（X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset、RateLimit-Policy）以及超出限流时的 429 响应示例，包含 Retry-After 头与 application/problem+json 内容类型。
适用场景
适合在设计与实现 REST API 时使用，例如规划资源与端点结构、选择 HTTP 方法与状态码、设计分页与过滤排序、制定版本策略、编写 OpenAPI 3.1 文档、选择认证与限流方案、定义错误响应与 Webhook 事件。
限制
资料未提供该技能的具体运行环境、依赖、安装方式、收费与价格信息，也未说明支持的具体平台或实现语言。以上均暂未提供。