用途:为设计、重构 REST 与 GraphQL API 提供专家级模式指导,适用于从零设计 API、为可扩展性与一致性重构现有 API、定义微服务服务契约、实现版本演进策略、统一错误处理与响应格式、设计大数据集分页、实现 HATEOAS/超媒体 API,以及编写 OpenAPI 或 GraphQL Schema 等 API 规范。
主要能力:以资源为导向的 REST 设计(URL 表示资源而非动作,语义化使用 GET/POST/PUT/PATCH/DELETE)、一致的命名约定(复数名词、嵌套资源、子资源、集合查询)、HTTP 状态码规范(200/201/202/204、400/401/403/404/409/422/429、500/502/503/504)。版本控制提供 URI、请求头、查询参数三种策略及 Sunset、Deprecation、Link 弃用头。分页提供基于 offset、cursor、keyset 三种模式及各自权衡。错误响应给出标准错误 schema(code、message、details、request_id、timestamp、documentation_url)与 CATEGORY_SPECIFIC_REASON 错误码模式。还涵盖过滤与搜索(查询参数、FIQL/RSQL、全文检索、稀疏字段集)、HATEOAS(HAL 与 JSON:API)、限流头(含 RFC 6585)、认证模式(Bearer、API Key、Basic)、幂等性(Idempotency-Key 与自然幂等)、缓存(ETag、Cache-Control)、GraphQL 查询、错误、Mutation 结构,以及最佳实践与反模式清单。
使用方式:资料以参考资料形式组织,设计流程见 skills/api-design-patterns/references/design-process.md。可按主题查阅对应章节,命令与代码示例保持原样,例如 Authorization: Bearer ...、Idempotency-Key 头、Cache-Control: max-age=3600, must-revalidate、filter=status==active 等。
适用场景与限制:适合 REST/GraphQL 设计、微服务契约、版本演进、分页与错误标准化。资料未提供具体安装命令、收费或平台支持信息,暂未提供相关细节。