api-designlisted

# API Design ## Coverage Design clear and evolvable API surfaces. Covers resources vs actions, route naming, request/response schemas, validation, status codes, pagination, filtering, sorting, idempotency, auth boundaries, error envelopes, rate-limit signals, versioning, deprecation, and contract examples. ## Philosophy An API is a product surface for another program. Its main job is stable meaning under change. Internal convenience should not leak into routes, schemas, or errors unless consumers actually need it. Prefer boring consistency. A small set of predictable patterns beats clever endpoint-specific behavior that every client has to rediscover. ## Method 1. Identify consumers and their tasks. 2. Model resources and actions separately. 3. Define request, response, and error schema examples. 4. Decide pagination, filtering, sorting, and field selection. 5. State auth, tenant, and permission boundaries. 6. Add idempotency and retry behavior for mutating or async operations. 7. Define versioning and deprecation rules before the first breaking change. 8. Add contract tests or fixtures. ## Evals This skill ships a comprehension-eval artifact at [`examples/evals/api-design.json`](https://github.com/jacob-balslev/skill-graph/blob/main/examples/evals/api-design.json). The checklist below is the authoring gate for API surface decisions; the eval file is the grader surface. ## Verification - [ ] Routes use consistent nouns/actions and avoid implementation leakage - [ ]