用途
本技能是一份面向开发者的 API 设计指南，旨在帮助设计易用、可维护的 API。当需要设计 API、编写端点文档或审查 API 架构时，可参考其中的最佳实践。
主要能力
REST API 原则
- 资源命名：使用名词而非动词（如
GET /users而非GET /getUsers），使用复数名词（如/users而非/user），并支持层级关系（如/users/{userId}/orders）。 - HTTP 方法：明确 GET、POST、PUT、PATCH、DELETE 的用途、幂等性与是否携带请求体。
- 状态码：区分成功（2xx）、客户端错误（4xx）与服务端错误（5xx），并给出各状态码含义。
- 响应格式：提供成功响应、集合响应（含 meta 与 links）和错误响应的 JSON 示例。
- 分页：介绍基于偏移量（offset）与基于游标（cursor）两种方式，推荐游标分页。
- 过滤、排序与字段选择：给出查询参数示例，如
?status=active、?sort=-created_at、?fields=id,name,email。 - 版本控制：介绍 URL 路径与请求头两种方式，推荐 URL 路径版本控制。
OpenAPI 规范
提供 OpenAPI 3.0.3 的 YAML 示例，包含 info、servers、paths、components 等结构，用于描述 API 端点与数据模型。
认证
介绍 API Key 与 Bearer Token（JWT、OAuth）两种方式，并说明如何在 OpenAPI 中声明安全方案。
限流
建议在响应中包含 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset 等头部，超限时返回 429 Too Many Requests。
安全清单
列出 HTTPS、认证、输入验证、输出编码、限流、CORS 配置、避免 URL 中携带敏感数据、审计日志等检查项。
gRPC 与 Protocol Buffers
提供 proto3 定义示例，并对比 gRPC 与 REST 在性能、流式传输、类型安全、浏览器支持、工具链和适用场景上的差异。
tRPC for TypeScript
给出服务端路由与客户端调用的 TypeScript 示例，说明 tRPC 适合客户端与服务端共享同一代码库的 monorepo 全栈 TypeScript 应用。
Webhook 设计模式
涵盖 Webhook 载荷格式、使用 HMAC-SHA256 的签名验证、重试策略（含具体时间间隔）以及基于事件 ID 的幂等处理。
API 版本控制策略
对比 URL 路径、查询参数、请求头、内容协商四种策略的优缺点，推荐使用 URL 路径版本控制，仅在破坏性变更时提升主版本号，同一版本内使用增量、非破坏性变更。
使用方式
该技能以文档形式提供，可在设计 API、编写端点文档或审查 API 架构时作为参考。资料中未提供具体的安装命令或调用方式。
适用场景
- 设计新的 REST 或 GraphQL API
- 编写 API 端点文档
- 审查现有 API 架构
- 选择 gRPC、tRPC 或 REST 等技术方案
- 设计 Webhook 与版本控制策略
限制
资料中未提供该技能的收费、价格、平台支持或具体安装步骤等信息。