用途：为 REST/GraphQL API 提供设计规范，让接口一致、可预测、向后兼容。适用场景包括设计新 API、新增端点、统一错误格式、实现分页与限流、规划版本演进，以及上线前审查。
主要能力：资源命名采用复数名词、小写与连字符（/users、/blog-posts）；HTTP 方法按语义使用（GET 读取、POST 创建、PUT 替换、PATCH 部分更新、DELETE 删除）；状态码覆盖 200、201、204、400、401、403、404、409、422、429、500；非 CRUD 操作以子资源动作表达（如 POST /users/{id}/activate、/orders/{id}/cancel、/auth/login）。错误响应统一为包含 code、message、details、requestId 的结构，避免暴露内部细节。分页提供游标式（?limit=20&cursor=xxx，适合实时数据）与偏移式（?page=2&limit=20 或 offset/limit）两种方案。限流包含 X-RateLimit-Limit、Remaining、Reset 及 429 时的 Retry-After。版本策略包括 URL 路径（/api/v1/）与 Header 方式，并区分需升版与不需升版的变更。查询参数支持过滤、范围、搜索、排序与字段选择。
使用方式：按主题加载参考文件（rest-patterns、error-handling、pagination、versioning、documentation、checklist）以获取对应细节；示例实现使用 Zod 校验过滤器、ApiError 类与错误处理中间件、游标编解码函数、基于 @upstash/ratelimit 的限流中间件。
限制：资料未提供 GraphQL 的详细模式、价格、平台与具体性能数据；上述内容为规范建议，落地时需结合具体语言与框架调整。