API设计规范

定位

API设计规范——REST 资源命名、版本与错误约定的常规指南 Skill

适用边界

• ✅ 适用：API设计、REST、版本策略、错误码、OAuth2、接口规范 等场景下的方法论指导与清单参考。
• ✅ 适用：用户需要结构化步骤、检查清单或最佳实践时。
• ❌ 不适用：需要实时数据或外部系统直连的高频自动化任务。
• ❌ 不适用：须由持牌专业人士出具的确定性结论（法律/医疗/财税等）。

触发词

API设计、REST、版本策略、错误码、OAuth2、接口规范。

核心方法

1. REST 资源命名与版本策略（兼容演进）
2. 统一错误码、分页与限流约定
3. 鉴权选型：API Key/OAuth2/JWT 适用对比
4. 文档与变更管理，避免破坏性更新

工作流程

1. 明确目标与场景边界。
2. 套用上述核心方法逐项执行或自查。
3. 输出结构化结果（清单/分级/建议）。
4. 标注不确定项与需人工复核的环节。

红线 / 注意事项

规范为通用建议；特定业务须权衡兼容性与演进节奏。

附：速查卡

详见 references/速查卡.md。