awesome-api-design
Designs or reviews an HTTP API's shape before code: resources, versioning, pagination, idempotency, filtering. Use when asked to design an API or an endpoint.
Khasky · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add khasky/awesome-agent-skills --skill awesome-api-designAbout this skill
name: awesome-api-design description: "Designs or reviews an HTTP API's shape before code: resources, versioning, pagination, idempotency, filtering. Use when asked to design an API or an endpoint." license: MIT metadata: author: Khasky tags: ["api", "design", "rest", "versioning", "pagination"] documentation: "https://github.com/khasky/awesome-agent-skills/tree/main/skills/awesome-api-design"
API Design
Shape an HTTP API so its consumers can build against it for years without a breaking surprise. The contract is the product: URLs, methods, payloads, errors, and evolution rules are decided here, deliberately — everything left implicit becomes an accidental contract the first client depends on.
When to Activate
- "Design the API for X", "review this API design / OpenAPI spec", "how should we version / paginate / handle retries".
- A design doc needs its API section made concrete (awesome-design-doc hands off here).
- A new endpoint is being added to an existing API and must match its conventions.
Do not activate to define the error envelope's fields or retry classification (awesome-error-standards owns that contract) or to audit implemented handlers for vulnerabilities (awesome-security-audit).
Work Process
- Inventory the incumbent conventions and the project's own words — an existing API's casing, id format, pagination style, and envelope win over any guideline here: consistency within one API beats global best practice. Only a new API starts from the defaults below. Read the recorded decisions (existing ADRs) and the project's glossary (
CONTEXT.md, a domain doc, or the terms its code and tests already use) before naming a single resource: a path is a public, long-lived name, and one that renames a concept the codebase already has costs every reader a translation. - Model resources, not procedures — nouns with identity and lifecycle (
/orders/{id}), actions as state transitions on them (POST /orders/{id}/cancelwhen a pure verb is unavoidable — never/doCancelOrder). Nest at most one level deep; deeper hierarchies become query filters (/comments?post_id=…), because every nesting level hardcodes an ownership assumption into every client URL. - Decide the evolution rules before v1 ships — additive changes (new optional field, new endpoint) go in place; anything breaking (remove/rename/retype a field, tighten validation) only ever creates a new version. Publish that taxonomy with the API so consumers know what is safe to ignore. Evolve by layering — a redesigned abstraction ships beside the old one and existing integrations keep working until their owners move; deprecation is announced with a sunset window, never enforced by an in-place change.
- Design list endpoints for growth — opaque cursor pagination (encode the
(sort_key, id)position, returnhas_more+next_cursorin a list envelope) over offset, which skips and duplicates rows under concurrent writes and dies on deep pages. Filtering and sorting are an allowlist of named parameters over indexed fields, never a pass-through to the query layer. - Make unsafe methods retry-safe — mutations accept an
Idempotency-Key; same key + same body replays the stored response, same key + different body is 409. Without it, every client retry is a potential duplicate side effect. (Retry classification and the envelope format: awesome-error-standards.) - Specify concurrency and partial updates — updates that can conflict get optimistic concurrency (
ETag+If-Match, 409 with the current version on mismatch); PATCH semantics are declared (merge-patch vs replace), and an empty PATCH is rejected, not silently a no-op. - Write the contract down as the source of truth — an OpenAPI/schema document that generates or validates the implementation, not prose that drifts from it. Ids are opaque and prefixed (
ord_…), timestamps ISO 8601 UTC, money integer minor units with currency, enums closed with a documented default for unknown values on the consumer side.
Design review checklist
When reviewing an existing design, walk the same decisions as findings:
- Naming and casing consistent across every endpoint; no mixed
camelCase/snake_casepayloads. - No verbs in resource paths except modeled state transitions; no RPC-style
/getXendpoints beside REST resources. - Every list endpoint paginated from day one — retrofitting pagination is a breaking change.
- Every mutation idempotent-by-key or documented as naturally idempotent.
- Error responses reference one stable envelope (awesome-error-standards) — not per-endpoint improvisation.
- Versioning and deprecation policy stated; no "we'll decide when we break something".
- Webhooks the API sends are treated as public surface: signed, versioned, redeliverable — same contract discipline as endpoints.
- Nothing in the response a client shouldn't see: internal ids, flags, or fields leaking through by serializer default.
Change review
When the input is a change to a shipped contract (a diff to a spec, schema, handler or payload), review the change, not the end state. Compatibility is never declared from the new schema alone: read the old and new shapes side by side, and the code on both sides of the wire. Walk four scenarios and record the result of each:
- Old writer, new reader: a payload produced before the change reaches code after it.
- New writer, old reader: a payload produced after the change reaches code that has not been updated yet (still-deployed servers, shipped mobile or SDK builds).
- Rollback: the old code returns while values only the new code writes are already stored or in flight.
- Payloads at rest: old-format messages in queues, cache entries, stored rows and files are read by new code, and new-format ones by old code after a rollback.
Search for consumers both ways, in every repository you can reach:
- A client reads a field the server stopped sending, renamed or retyped. This breaks silently: no error, a missing or wrong va