用途：该技能聚焦协议层面的 API 设计决策，而非具体语言或框架实现，适用于从零设计公开或内部 API、评审现有 API 的一致性与可用性、在 REST 与 GraphQL 之间选型、规划 API 版本与迁移策略、定义跨服务错误响应契约、为团队建立 API 标准。
主要能力：一是 REST 设计原则，资源用名词而非动词（如 /orders），用 HTTP 方法表达操作，集合用复数名词，嵌套不超过两层，合理使用状态码，支持内容协商，可选 HATEOAS。二是 GraphQL 设计原则，主张 schema 优先，查询/变更/订阅分别负责读、写与流式数据，用类型系统约束（非空、枚举、输入类型），避免过深嵌套，用批处理解决 N+1，限制查询深度与复杂度。三是提供 REST 与 GraphQL 对比（数据获取、缓存、文件上传、实时、错误处理、版本化等），建议外部 API 用 REST、内部前后端通信用 GraphQL。四是错误处理，推荐 REST 使用 RFC 7807 Problem Details 格式，包含机器可读的 type 或 code、可读 detail、字段级错误与请求 ID，禁止泄露堆栈、内部路径或 SQL。五是版本化策略，比较 URL 路径、Accept 头与查询参数三种方式，仅破坏性变更才升主版本，优先加法式演进，弃用需给出日落日期与迁移指南。六是分页，对比 offset 与 cursor，建议设默认与最大页大小并返回 hasNextPage 等元数据，高频变化数据用 cursor，报表类用 offset。七是认证与授权，介绍 API key、OAuth 2.0、JWT、会话 Cookie 的适用场景与注意事项，强调 HTTPS、Bearer 头传输、作用域控制、401 与 403 区分、登录端点限流。八是常见反模式与发布前质量检查清单。
使用方式与限制：资料未提供具体安装命令或调用步骤，暂未提供。该技能为文档型参考，不包含可直接运行的代码或工具。所有示例为设计约定示意，实际实现细节、性能数据与收费情况暂未提供。