Api Design

API Design

This skill turns "I need an endpoint" into an API that is consistent, predictable, and safe to evolve. It encodes the conventions that the best public APIs (Stripe, Microsoft, GitHub) share.

Analogy: an API is the menu of a restaurant. A good menu is consistent — every dish described the same way, prices where you expect, no surprises. A messy menu makes every order a negotiation.

Discovery (max 3 questions, only if unknown)

1. Who consumes this — your own React SPA only, or also mobile / partners / the public?
2. Is it mostly simple CRUD, or deeply nested reads across many relations?
3. Is it public-facing (needs versioning + stability) or internal?

Step 1 — REST vs GraphQL (decide first)

Default to REST. Reach for GraphQL only when: clients need flexible, deeply nested reads across many relations; you have multiple divergent clients (web + mobile + partners); or you're composing several backend services. For a single React SPA on one Postgres DB, REST (or tRPC for end-to-end TS types) is simpler and cacheable.

If you do choose GraphQL:

• Solve N+1 from day one with DataLoader (batch + cache per request).
• Design the schema around the domain graph, not DB tables.
• Paginate every list field (Relay-style edges/node/pageInfo); enforce depth/complexity limits.
• Mutations return the mutated object so clients update cache without a refetch.

Step 2 — REST conventions (the defaults)

• Resources are plural nouns: /invoices, /invoices/{id}/lines. Verbs are HTTP methods, not paths. Non-CRUD actions: /invoices/{id}:send.
• Version from day one: URI versioning /v1/..., even with only a v1.
• Cursor-based pagination by default (opaque cursor + has_more), not offset — stays consistent on insert, avoids slow OFFSET scans. Default page 25, max 100.
• One consistent error envelope with the correct HTTP status:

  jsonCopy code
  { "error": { "type": "validation_error", "code": "invalid_email", "message": "…", "param": "email" } }
  

  Never return 200 on failure.
• Status codes: 201 + Location on create, 204 on delete, 409 conflict, 422 validation, 429 + Retry-After rate limit.
• Idempotency: require an Idempotency-Key header on unsafe POSTs (payments, signups). Store key→response for 24h; replay returns the original — no double-charge on retry. GET/PUT/DELETE are idempotent by spec.
• Consistency: ISO-8601 UTC timestamps, one field-casing convention (snake_case or camelCase) across the whole API.
• Filtering over endpoint sprawl: ?status=open&fields=id,total instead of a new endpoint per view.

Step 3 — Validate env config at the boundary

Every API needs config, and a missing var should fail loudly at boot, not silently in prod:

• Validate all env vars at startup with a zod schema (or t3-env on Vite/Next). Fail fast on a missing/malformed var.
• Separate server secrets from client config: on Vite, only VITE_-prefixed vars reach the browser — never put a secret there.
• Commit .env.example (names + dummy values); never commit real .env*. (Secrets handling lives in the secure-coding skill.)

Handoff

API shape decided here feeds the data-modeling skill (the schema behind it), the auth skill (who can call each endpoint), and secure-coding (validation + rate limits on each handler).

Step 4 — Failure semantics (decide them per endpoint)

• Check every { error }. Many SDKs return errors instead of throwing; an unchecked one is a silent failure.
• Three outcomes, not two: succeeded, refused, unknown. "Could not read" is not "not found"; a timeout is not "nothing changed".
• A retry must be safe. "The response was lost" is not "it was not saved" — check what exists before inserting again.
• Send only the fields the user changed, so a form cannot overwrite what moved in the meantime.
• One server-side writer for rewards, credits, balances and payment states.
• Chunk id lists and paginate reads; auto-generated APIs cap rows and URLs have a length limit.

Field notes

references/field-notes.md holds 11 API failures from production apps. The three that cost the most:

1. Failures invisible for days because an SDK's returned error was never read.
2. A duplicated order that took four rounds to fix.
3. Editing one field of a record silently reset another.

Output

Deliver: the REST-vs-GraphQL call with reason, the route list with methods + status codes, the error envelope, the pagination scheme, and a zod env schema for the service.

Reference

microsoft/api-guidelines (~23k⭐), Stripe API design + idempotency docs, donnemartin/system-design-primer (~352k⭐), graphql/dataloader (~13k⭐), t3-oss/t3-env (~4k⭐), colinhacks/zod (~43k⭐).