该技能名为 API Design Ops，定位为覆盖 REST（进阶）、gRPC 与 GraphQL 的 API 设计模式集合，用于构建生产级 API 时提供决策框架、设计模式与实现指导。以下内容均来自资料本身。
【用途与选型】 资料提供了一棵“API 风格决策树”。内部微服务间调用：需要高吞吐、低延迟则选 gRPC；需要流式（实时数据、日志）则选 gRPC 双向流；简单请求/响应且团队熟悉则选 REST。公开 API：第三方开发者消费选 REST（兼容性最广）；移动应用数据需求多样选 GraphQL；仅浏览器端的简单 CRUD 选 REST。自有应用前端：多个客户端、数据形态不同选 GraphQL；单一客户端、数据直接选 REST；需要实时更新则选 GraphQL 订阅或 SSE。IoT/嵌入式/受限设备：看重二进制效率选 gRPC；仅有 HTTP 环境选 REST。
【主要能力】
- 快速对比表：从传输（HTTP/1.1+、HTTP/2、HTTP）、序列化（JSON、Protobuf、JSON）、Schema（OpenAPI 可选、.proto 必需、SDL 必需）、浏览器支持、缓存、学习曲线、代码生成、流式、过度获取、文件上传等维度对比 REST/gRPC/GraphQL。
- REST 资源设计速查：给出集合、单例、子集合的 URL 形式，以及 POST/PUT/PATCH/DELETE 的语义；命名规则包括集合用复数名词、多词用 kebab-case、URL 中不用动词、层级最多 3 层。
- 方法与状态码表：列出各方法在成功、空、无效、未找到、冲突下的状态码，如 POST 成功为 201 + Location。
- HATEOAS：何时值得（公开 API、长期存续、频繁演进）与何时跳过（内部微服务、移动后端、可接受紧耦合），并给出 _links 示例。
- 分页决策树：稳定数据且需跳页用 offset 分页（大偏移会慢、插入时不一致）；大数据集且仅向前遍历用 cursor 分页（不能随机跳页但一致且快）；实时流按时间戳或 ID 排序用 keyset 分页（需唯一顺序列、不能跳页）。附响应信封示例（data + pagination）。
- 错误响应：建议所有 API 采用 RFC 7807/9457 Problem Details，字段包括 type、title、status、detail（均必需）与 instance、扩展字段（可选）；并给出校验错误示例（errors 数组含 field、message、code）。
- 版本化策略：URL 路径、Accept 头、查询参数、日期基四种方式各自的示例与优劣；建议公开 API 用 URL 路径版本，内部 API 用头部或不版本化，演进型 API（如有工程投入）用 Stripe 式日期基。并列出破坏性变更（删字段、改名、改类型、加必填字段、改 URL 结构、改错误格式、删端点）与非破坏性变更（加可选字段、加响应字段、加端点、加枚举值）。
- 限流设计：算法包括令牌桶（允许突发）、滑动窗口（平滑无突发）、固定窗口（简单、边界可能突发）、漏桶（恒定输出）；给出响应头 X-RateLimit-Limit/Remaining/Reset 与 Retry-After，以及 429 响应体示例。
- 幂等性：GET/PUT/DELETE 规范上幂等无需键，PATCH 建议关键操作用键，POST 需键（支付、订单、转账等）；实现步骤包括接收 Idempotency-Key 头、查存储、命中则返回存储响应、未命中则处理并存储，键 24–48 小时后过期。
- 认证概览：API Key（服务器间、内部、简单，低-中）、JWT Bearer（无状态、微服务，中-高）、OAuth2 + PKCE（第三方访问、用户委托，高）、mTLS（服务网格、零信任，很高）；并给出去向决策指南与“快速原型可用 API Key 但需规划迁移”的提示。
- 陷阱表：涵盖“非破坏性”发布中实际破坏、REST 的 N+1、过度获取、获取不足、CORS 配置错误、缺失 Content-Type、大负载未分页、日期格式不一致、无请求 ID、枚举演进、缺少幂等、GraphQL 查询复杂度无界等，并给出预防措施。
【参考文件】 资料列出四个参考文件：references/rest-advanced.md（资源建模、PATCH 策略、缓存、webhook、批量操作）、references/grpc.md（Protobuf、服务定义、Go/Rust、流式、错误处理）、references/graphql.md（Schema 设计、解析器、DataLoader、联邦、性能）、references/api-security.md（JWT、OAuth2、CORS、限流、OWASP API Top 10）。
【限制与暂未提供】 资料未提供安装命令、运行环境要求、支持的平台、收费或价格信息、实际可执行的操作步骤，也未说明如何在工具中调用该技能，以上均暂未提供。
【适用场景】 适用于在为内部微服务、面向第三方的公开 API、自有前端、IoT/嵌入式设备选择与设计 API 时参考；也适用于制定 REST 资源命名、分页、错误格式、版本化、限流、幂等与认证策略；以及排查 N+1、过度获取、CORS、日期格式、枚举演进等常见问题。