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

1. 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.
2. Model resources, not procedures — nouns with identity and lifecycle (/orders/{id}), actions as state transitions on them (POST /orders/{id}/cancel when 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.
3. 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.
4. Design list endpoints for growth — opaque cursor pagination (encode the (sort_key, id) position, return has_more + next_cursor in 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.
5. 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.)
6. 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.
7. 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.