| name | api-design |
| description | Design and review HTTP/REST (and choose between REST/GraphQL/gRPC) APIs that are contract-first, resource-oriented, backward-compatible, and secure by default. Use whenever the task touches an API surface — designing an API, adding or changing an endpoint or route, picking an HTTP method or status code, naming resources, paginating a list, versioning, deprecating a field, modeling errors, idempotency, concurrency, webhooks, or writing an OpenAPI spec. Triggers: "design an API", "add an endpoint", API, REST, endpoint, route, HTTP, versioning, pagination, webhook, OpenAPI, idempotency. Not for pure UI work — see building-frontend-ui. |
API Design
A good API is a contract you can evolve without breaking the people who depend on it. Design the contract first, model resources not actions, use HTTP the way it is specified, stay backward-compatible, and make security and operability the default — not an afterthought.
This skill is protocol-agnostic at the workflow level; the canonical detail lives in references/ and is loaded on demand.
Read first (always)
List learnings/ and read every file whose name looks relevant to the current task — the project's versioning policy, its error envelope, its auth model, its naming conventions, and provider-specific webhook quirks live there and override the defaults in this file. If a learning conflicts with this SKILL.md, the learning wins — mention it to the user.
Tradeoff — when to apply, when to lighten up
Apply the full discipline for any API with external or cross-team consumers, or anything that persists state. Lighten the ceremony for a private, single-consumer endpoint you fully control on both sides and can change atomically — but never lighten the security floor (authorization, input validation, no secrets in URLs).
Workflow
-
Choose the protocol deliberately. REST for resource CRUD and broad client reach; GraphQL when clients need flexible, client-shaped queries over a graph; gRPC for low-latency internal service-to-service. Don't default to GraphQL/gRPC because they're new. State the choice and why.
→ verify: you can name the consumer and why this protocol fits it.
-
Design contract-first. Write the OpenAPI (or proto/SDL) spec before the code; review it, then generate or hand-write handlers against it. Lint the spec in CI (e.g. Spectral) so drift fails the build.
→ verify: the spec exists and is the source of truth, not reverse-engineered from code.
-
Model resources (nouns), not actions. A resource is a thing with an identity; collections are plural. Unusual operations become sub-resources or state, not verbs in the path. See references/rest-conventions.md.
→ verify: no verb in any path.
-
Use HTTP method + status-code semantics correctly. GET/HEAD safe and idempotent, PUT/DELETE idempotent, PATCH partial, POST creates/non-idempotent. Status code carries the outcome; the body carries the data or the error. See references/rest-conventions.md.
→ verify: no 200 OK with an error in the body.
-
Apply consistent conventions everywhere. One casing for paths, one for fields; pluralized collections; opaque IDs (don't leak DB sequence/structure). Inconsistency is a permanent tax on every consumer.
→ verify: a reader can predict the shape of an endpoint they haven't seen.
-
Never break consumers. Additive-only changes within a version; breaking changes need a new version and a deprecation window with Deprecation/Sunset headers. Adding pagination to a previously-unpaginated list is a breaking change. See references/versioning-and-compatibility.md.
→ verify: every change is classified additive or breaking before you ship it.
-
Standardize errors. Use RFC 9457 application/problem+json with a stable machine-readable code. HTTP status must match the body. Never leak stack traces. See references/errors-idempotency-concurrency.md.
→ verify: every error path returns the same envelope shape and a stable code.
-
Paginate every list from day one. Cursor-based (page_size + page_token / next link) preferred over offset. Retrofitting pagination later breaks clients.
→ verify: no unbounded list endpoint exists.
-
Make writes safe to retry. Idempotency-Key for non-idempotent POST (store and replay the first response); optimistic concurrency with ETag + If-Match → 412 on conflict. See references/errors-idempotency-concurrency.md.
→ verify: a client that retries a POST after a timeout cannot double-charge / double-create.
-
Security by default. TLS only; validate tokens server-side; per-object authorization (not just role); no secrets in URLs; validate input against the schema; rate-limit; CORS allow-list. See references/security.md.
→ verify: object-level authorization is checked on every request that names an object.
-
Capture a learning (final step). If you hit a convention, constraint, or trap not already in this file or references/, append a learnings/YYYY-MM-DD-slug.md. Otherwise skip.
Anti-patterns (reject on sight)
- Verbs in paths —
POST /createUser, /getOrders. Use POST /users, GET /orders.
200 OK with an error in the body. The status code is the outcome; clients and proxies rely on it.- Leaking internal/DB models — exposing column names, internal enums, sequence IDs, or join structure as the public shape. Map to a deliberate DTO.
- Chatty endpoints / N+1 — forcing clients to make many round-trips to assemble one view. Offer expansion (
expand=) or a coarser resource.
- Breaking changes without a new version — including renaming/removing a field, changing a type or default, or adding pagination to a previously-unpaginated list.
- Inconsistent conventions — mixed casing, singular and plural collections, sometimes-wrapped responses.
- Non-idempotent POST with no idempotency key — any retry double-creates.
- Sensitive data in URLs — tokens, PII, secrets in path or query; they land in logs, history, and referers.
- Missing object-level authorization (BOLA) — checking authentication but not whether this caller may touch this object. OWASP API #1.
- Exposing stack traces — internal class names, file paths, SQL in the error body.
- Unbounded list endpoints —
GET /events returning everything.
Capture a learning
When you finish, ask: did I encounter a convention, constraint, or trap that wasn't in this SKILL.md or references/? (A project-specific versioning policy, a non-standard error envelope the org has standardized on, a webhook provider's signing scheme, a mandated header.) If yes, append a learnings/YYYY-MM-DD-slug.md following learnings/README.md. If no, skip — don't write noise.
See also
references/rest-conventions.md — resource modeling, naming, methods, status codes, pagination, filtering, caching.references/versioning-and-compatibility.md — versioning strategies, additive vs breaking changes, deprecation policy.references/errors-idempotency-concurrency.md — problem+json, idempotency keys, optimistic concurrency, retries, long-running ops, webhooks.references/security.md — TLS, OAuth2/OIDC, BOLA/BFLA, input validation, rate limiting, CORS, data exposure.developing-features skill — general production rules and the full security reference (the API surface is one boundary among several).reviewing-code skill — review a diff that changes an API surface.documenting-features skill — capture the API contract, ADRs, and the domain model alongside the code.learnings/ — project-specific API conventions accumulated over time.
