API Design Principles
Use when designing, reviewing, documenting, versioning, or migrating REST or GraphQL APIs and their client, security, performance, and compatibility contracts.
Install
npx skills add sandbaseai/workbuddy-skill --skill api-design-principlesgit clone --depth 1 https://github.com/sandbaseai/workbuddy-skill.git /tmp/workbuddy-skill
mkdir -p ~/.claude/skills
cp -r /tmp/workbuddy-skill/skills/api-design-principles ~/.claude/skills/api-design-principlesPersonal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.
From the SKILL.md
# API Design Principles 设计可理解、可演进、可验证的 REST 或 GraphQL API。先建立资源、契约和兼容性边界,再讨论实现;不要把数据库结构、单个客户端便利或未经授权的线上行为直接变成公共 API。 ## 范围和安全边界 - 明确 API 所有者、消费者、环境、身份/租户模型、数据分类、SLO、兼容窗口和变更授权。 - 设计与评审默认只读规格、schema、现有调用、契约测试、指标摘要和脱敏样例;不向生产发送写请求、不迁移数据、不改限流/WAF/权限策略。 - 请求/响应示例使用合成数据,隐藏令牌、Cookie、个人数据、内部主机名和完整错误堆栈。 - 将设计决策、观察事实、推导和未知分开;没有消费者或业务意图证据时标记 `[ASK USER]`/`[TODO]`,不要猜测。 ## 资源与 HTTP 语义 REST 路径使用稳定的资源名词和层级,动作由 HTTP 方法表达:`GET` 安全且幂等,`POST` 创建或非幂等动作,`PUT` 全量替换且幂等,`PATCH` 局部更新,`DELETE` 删除且应可重复处理。若业务动作不适合资源模型,显式记录命名和幂等性理由,不用含糊的动词路径掩盖副作用。 为每个操作定义认证、授权、租户隔离、输入校验、状态码、响应 schema、错误码、超时、重试和审计字段。区分 2xx、4xx、5xx、业务拒绝、超时、部分成功和异步受理;不要把所有失败映射为 200,也不要泄露内部异常。 ## 契约优先与 GraphQL REST 使用 OpenAPI 或等价的版本化契约,GraphQL 先设计类型/schema,再实现 resolver。每个字段说明可空性、格式、敏感级别、所有权、演进策略和默认值。GraphQL mutation 返回结构化业务错误,查询和 resolver 做输入授权;使用 DataLoader 或等价批处理避免 N+1,并限制深度、复杂度、分页大小和执行时间,防止资源耗尽。 ## 分页、过滤与一致性 大集合必须有明确上限、排序稳定性、游标/偏移策略、下一页语义、重复/遗漏风险和快照一致性。过滤、排序和字段选择列入契约并做索引/成本评估;不能把任意查询表达式直接暴露给服务端。报告空页、删除/并发更新、时区和最终一致性对客户端的影响。 ## 幂等、重试与并发 对创建、支付、消息发送、导入等可能重试的操作定义幂等键、作用域、保存时长、冲突响应和去重证据。声明哪些操作可安全重试,设置客户端/服务端退避、超时和重试预算;不要对非幂等 POST 自动重放。并发更新需选择版本号、ETag/If-Match、条件写或明确的 last-write-wins,并说明冲突处理。 ## 版本化与演进 选择 URL、媒体类型/请求头或 schema 演进策略,并记录选择理由。破坏性变更包括删除/重命名字段、收窄枚举、改变含义、改变错误/排序/默认值、权限扩大和副作用变化;每项都要有消费者影响、迁移步骤、兼容窗口、弃用通知、契约测试、回滚/双读双写计划和删除日期。优先向后兼容新增字段,但仍要考虑未知字段、客户端严格解析和字段敏感性。 ## 限流、可观测性和文档
Details
- Skill name
api-design-principles- Repository
- sandbaseai/workbuddy-skill
- Path
skills/api-design-principles/SKILL.md- License
- MIT
- Repo updated
- 8 September 2026
FAQ
What does the API Design Principles skill do?
Use when designing, reviewing, documenting, versioning, or migrating REST or GraphQL APIs and their client, security, performance, and compatibility contracts.
How do I install the API Design Principles skill?
skills CLI (Claude Code, Cursor, Codex and more): npx skills add sandbaseai/workbuddy-skill --skill api-design-principles. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.
Is API Design Principles popular?
It lives in sandbaseai/workbuddy-skill, which has 9 GitHub stars and 3 forks.
Related skills
Access Control Security Best Practices
9sandbaseai/workbuddy-skill
Design, review, implement, and verify least-privilege access controls across users, services, tenants, resources, and administrative workflows.
Accessibility Review
9sandbaseai/workbuddy-skill
Use when reviewing a web interface or interaction for semantic, keyboard, focus, screen-reader, ARIA, and contrast accessibility risks.
Acquire Codebase Knowledge
9sandbaseai/workbuddy-skill
Use when the user asks to map, document, or onboard into an existing codebase and needs evidence-backed architecture, structure, conventions, integrations, testing, and concerns documentation.
API Documentation
9sandbaseai/workbuddy-skill
Use when creating, editing, restructuring, or reviewing a service API document; keep operations, requests, responses, errors, types, routes, examples, and conventions precise and aligned with the authoritative contract.
API Resilience Engineering
9sandbaseai/workbuddy-skill
Use when designing, implementing, reviewing, testing, or diagnosing API timeouts, retries, idempotency, rate limits, concurrency limits, circuit breakers, bulkheads, backpressure, load shedding, or ambiguous outcomes.
Spec Review Local
5adelrioj/claude-skills
Use when a brainstorming design spec has been written and needs adversarial review before implementation planning, using a local model served by LMStudio (via the pi CLI) as the independent reviewer. Works offline — no hosted API needed. Triggers on: spec review local, local spec review, review spec locally, lmstudio review, review spec, spec review.
Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.