api-design

# API Design <!-- routing-eval reads this line; it lives in the BODY so the always-on skill LISTING stays inside Claude Code's budget (1% of the context window) — an overflowing listing gets descriptions truncated or dropped, which strips the very keywords a match depends on. --> Trigger phrases: "api design", "api contract", "api versioning", "openapi", "swagger", "rest contract", "breaking api change" Goal: a contract the consumer can **predict** and that can **evolve** without breaking. Once published, a public API is a commitment; a breaking change is expensive. Stack-agnostic (REST as the baseline; GraphQL/gRPC follow similar principles). ## Checklist - [ ] Resource names are **consistent** (plural nouns, a single `kebab`/`camel` style), resources not verbs - [ ] Correct HTTP semantics: GET (side-effect free) · POST · PUT/PATCH · DELETE; correct **status code** - [ ] A uniform **error model**: machine-readable code + human message + (if any) field details - [ ] A clear **versioning** strategy (URL `/v1` or header); a breaking change means a new version - [ ] **Pagination/filtering/sorting** defined and consistent on large collections - [ ] **Backward compatibility**: adding a field is additive; removing a field or changing its meaning is breaking → version - [ ] **Idempotency** (for POST/payment-like cases) supported via a key when needed - [ ] The contract is documented in **OpenAPI**; example request/response present (coordinate with `docs-writer`) ## How...