api-design

<objective> Shape an HTTP or GraphQL API so callers get predictable, evolvable, and honest semantics. The deliverable is a concrete endpoint/schema sketch with: URL or operation names, method/verb, request shape, response shape, error shape, auth model, pagination strategy, and versioning stance. Optimize for "clients that exist in 2 years" over "client that's easy to write today". </objective> <context> GSD-2 has `design-an-interface` for general module-interface design; this skill is the HTTP/GraphQL specialization. REST and GraphQL carry baggage — status codes, verbs, nullability, pagination — that a generic interface-design discussion glosses over. Invocation points: - Adding a new public API endpoint - Redesigning an internal API boundary between services - Code review of a PR that introduces HTTP handlers - A slice whose acceptance criteria include "the API works" - A GraphQL schema change </context> <core_principle> **CALLERS OUTLIVE YOUR ASSUMPTIONS.** An API you ship today has to keep working when your internals change, when the mobile app version two is still in use, and when a third party integrates against it. Design for extension, not just for the current caller. **HONEST STATUS CODES.** 200 OK with `{"error": "not found"}` is a lie. 404 says not found. Use the HTTP semantics the protocol offers — HTTP clients, caches, and intermediaries rely on them. **PAGINATION IS NON-OPTIONAL.** Any list endpoint that doesn't paginate will eventually get a request for "all records" that kills your database. </core_principle> <process> ## Step 1: Gather the contract Answer, or ask (one round, 1–3 questions): 1. **Who are the callers?** Internal service / mobile app / public third-party / same-repo frontend. 2. **What's the versioning stance?** None / URL-path (`/v1/`) / header-based / GraphQL schema evolution. 3. **Auth model?** Public / API key / OAuth / session cookie / mTLS / none-but-internal-only. 4. **Idempotency expectation?** Is a retry safe? Required? 5. **Consistency model?** Read-your-writes, eventual, serializable? ## Step 2: Resource and operation naming ### REST - Nouns not verbs in URLs: `POST /users`, not `POST /createUser`. - Plural resources: `/users/42`, not `/user/42`. - Nested only when the relationship is hierarchical and the child has no independent identity: `/users/42/sessions/3`. Otherwise flat: `/sessions/3?userId=42`. - Use subresources for actions that don't fit CRUD: `POST /users/42:deactivate` (colon syntax) or `POST /users/42/actions/deactivate`. ### GraphQL - Queries are nouns; mutations are verbs: `user(id)`, `createUser(input)`, `deactivateUser(id)`. - Group related mutations under an input type: `createUser(input: CreateUserInput!)`. - Return the affected object plus any derived/computed fields from mutations — lets clients avoid a refetch. ## Step 3: Methods and status codes ### REST | Method | Intent | Idempotent? | Default success | |---|---|---|---| | GET | Read | Yes | 200, or 304 if conditional | | POST | Create or non-idempotent action | No | 201 with `Location` on create, 200 on action | | PUT | Replace (full-object) | Yes | 200 with body, or 204 | | PATCH | Partial update | No (usually) | 200 with body | | DELETE | Remove | Yes | 204 | Errors: - 400: caller screwed up the request shape - 401: no/invalid auth - 403: authed but not allowed - 404: resource doesn't exist - 409: conflict (version mismatch, unique constraint) - 410: gone (vs 404 when the resource previously existed and you want to signal that) - 422: validation failed - 429: rate-limited — include `Retry-After` - 500: genuinely unexpected server error - 503: service down or overloaded — include `Retry-After` Never 200-with-error-body. Never 500 for a 4xx cause. ### GraphQL - Top-level errors (`errors[]`) for transport-level failures. Domain errors (validation, not-found, forbidden) go in the typed return — use a union or result type. - Partial results are expected; design the schema so `null` on a field is meaningful, not a signal of generic failure. ## Step 4: Pagination - **Cursor-based by default.** Opaque cursor string, `limit`, return `nextCursor` when more exists. Scales, stable under writes. - **Offset-based only when:** dataset is small, user needs jump-to-page semantics (admin tables), and you're willing to accept stability drift. - **Never "return everything"** as default. Put a hard upper bound on `limit` (e.g., 200). - GraphQL: use Relay-style connections (`edges`, `pageInfo`) if the ecosystem expects it; otherwise a simpler `{items, nextCursor}` is fine. ## Step 5: Error shape Standardize one shape and use it everywhere. Example REST: ```json { "error": { "code": "user_not_found", "message": "No user with id 42", "details": { "userId": 42 }, "requestId": "req_abc123" } } ``` - `code` is machine-readable; stable; documented. - `message` is human-readable; can change. - `details` carries structured context. - `requestId` lets callers report bugs. Errors don't leak stack traces, file paths, or internal queries. ## Step 6: Idempotency, caching, concurrency - **Idempotency keys** for POST operations that mustn't double-execute on retry. Caller passes `Idempotency-Key: <uuid>`; server dedupes for a window. - **ETags** for GET + conditional updates (`If-Match` on PUT/PATCH). - **Cache-Control** on GETs that are safely cacheable. - **Optimistic concurrency:** when multiple writers collide, 409 with the current state. Don't silently clobber. ## Step 7: Versioning and evolution - **Additive changes are free:** new optional fields, new endpoints, new optional query params. - **Breaking changes need a plan:** path-versioned (`/v2/`), sunset headers on `/v1/`, deprecation window communicated. Or, for GraphQL, `@deprecated` on fields with a migration note. - **Document the contract:** OpenAPI/GraphQL SDL. Keep it in the repo. Make it part of the PR that introduces the change. ## Step 8: Review or write it up If this is a review, produce findings in the same shape as `security-review` / `review` — file:line, category, recommendation. If this is a new design, produce: ```markdown ## <API name> ### Scope <what the API is for, who calls it> ### Endpoints / Operations - `POST /users` — create user. Request: `{email, name}`. Response 201: `{id, email, name, createdAt}` + `Location: /users/<id>`. Errors: 409 email taken, 422 invalid. - ... ### Auth <model + where to put the credential> ### Pagination <cursor shape, max limit> ### Error shape <one canonical shape> ### Idempotency / concurrency <rules> ### Versioning <stance + how breaking changes will be handled> ### OpenAPI / SDL <link or inline> ``` Append architectural decisions to `.gsd/DECISIONS.md`. </process> <anti_patterns> - **200 OK with `{"error": "..."}`.** Lies to caches, proxies, retry libraries. - **Unbounded list endpoints.** `GET /users` without a `limit` cap will bite you. - **Offset pagination at scale.** Drifts under writes; slow at high offsets. - **Free-form error messages with no code.** Machine callers can't branch on prose. - **Breaking changes in-place.** Callers break; versioning exists for a reason. - **Ignoring idempotency on retriable POSTs.** Double-charges, duplicate records. - **Auth checks at the handler only, not the service layer.** Defense in depth. </anti_patterns> <success_criteria> - [ ] Every endpoint/operation has named request, response, and error shapes. - [ ] Status codes match HTTP semantics — no 200-with-error. - [ ] List endpoints paginate; max limit is documented. - [ ] A single error shape is used everywhere, with a machine-readable code. - [ ] Versioning stance is stated — even if the answer is "additive only for now." - [ ] OpenAPI/SDL reflects the design and lives in the repo. - [ ] Decisions appear in `.gsd/DECISIONS.md`. </success_criteria>