api_design v1.0.1

name: "api_design" description: "Design HTTP APIs that age well: resource modeling, versioning and deprecation policy, error conventions (RFC 9457 problem details), pagination, idempotency, and docs-first OpenAPI contracts. Triggers when someone asks to design an API, add or review endpoints, set up versioning, fix inconsistent errors, or establish API design standards."

API Design

Purpose

Design REST/HTTP APIs around resources (not actions), write a machine-readable contract (OpenAPI 3.1) before code, and bake in versioning, error conventions, and pagination so the API can evolve without breaking clients.

Workflow

1. Model resources. Identify domain nouns and map each to a plural collection path: /users, /orders. Nest only where ownership is real (/users/{id}/orders). No verbs in paths — HTTP methods express actions. If an endpoint wants a verb, it is a smell; model it as a resource instead (e.g. POST /reports not /generateReport) or, rarely, a clearly-named controller sub-resource (POST /orders/{id}/cancellations).
2. Assign methods and semantics. GET = retrieve (safe, idempotent); POST = create (not idempotent — require an Idempotency-Key header for retries); PUT = full replace (idempotent); PATCH = partial update; DELETE = remove (idempotent). Return 201 on create, 204 on successful delete, 410 Gone (never 404) for sunset resources.
3. Fix the error contract. Every error returns the same envelope: RFC 9457 problem details (type, title, status, detail, instance) plus one machine-readable code extension. Validation failures include field-level detail. Never leak stack traces or internals in production.
4. Paginate every collection. No unbounded list responses. Cursor-based pagination for feeds/large datasets, page-based for static data. Include rate-limit headers on all responses.
5. Write the OpenAPI 3.1 contract first. One document is the source of truth. Generate mock servers (Prism), client SDKs, and contract tests (Schemathesis/Pact) from it. If spec and code disagree, the spec is the bug — fix one of them.
6. Set the versioning and deprecation policy. Bump the major version (/v1 → /v2) only on breaking changes; additive, backward-compatible changes stay on the same version. Version the whole API surface, never individual endpoints. Support N and N-1 concurrently. Deprecated responses carry Sunset (RFC 8594, HTTP-date) and Deprecation headers, deprecated: true in OpenAPI, and a changelog entry with a migration guide.
7. Lint the design. Run bin/api-lint.py against the OpenAPI file to catch verb-in-path, naming, missing-error-response, and unversioned-collection violations before review.

Output Contract

• An OpenAPI 3.1 document covering every endpoint, with consistent resource naming, the error envelope defined once in components and referenced everywhere, deprecated: true plus sunset dates on retiring operations, and pagination parameters on all list endpoints.
• A changelog entry for any breaking change plus a migration guide and an announced sunset date (realistic window: months, not days).
• Every claim in the design traceable to the contract or an RFC — no hand-wavy "probably fine".

Operating Rules

1. Never invent standards. Verify RFC numbers before citing them: Sunset is RFC 8594; problem details are RFC 9457 (not the obsolete 7807); the Deprecation header is RFC 9745 (Standards Track, 2025) — its value is an RFC 9651 structured-field date (@-prefixed Unix timestamp, e.g. Deprecation: @1768435200), not an HTTP-date. Unverifiable = cut or label as opinion.
2. The contract is the design. If an endpoint cannot be expressed cleanly in OpenAPI, the design is wrong, not the spec.
3. Additive changes don't version. New endpoints, optional fields, and optional query params ship on the current version. Bump only when existing clients can break: removed/renamed fields, tightened validation, changed status codes, new required fields, changed auth.
4. Errors are UX. Every error response must tell the caller what went wrong, which field caused it, and a stable code a machine can switch on. "Internal Server Error" alone is a design failure.
5. Idempotency is a requirement, not a feature. Any non-idempotent mutation (POST) gets an Idempotency-Key mechanism; document its behavior on retry.
6. No verbs in paths, ever. If the team demands one, record it as a deliberate exception with an expiry, not a precedent.
7. Deprecation is a lifecycle, not a label. Deprecated means: headers on every response, sunset date announced, migration guide published, usage logged so you know who hasn't moved.
8. Skip this skill's weight for RPC internals. For high-performance service-to-service RPC, gRPC beats REST — say so instead of forcing REST onto it. For complex, client-driven querying, GraphQL beats REST — say so.