API Design

API Design

Turns "we need an API for X" into a concrete spec — protocol, resources, schemas, and the cross-cutting concerns that actually bite in production.

Current context

• Existing API specs: !ls .context/architecture/api/ 2>/dev/null || echo "(none yet)"

Decision tree

• What kind of API does the user need?
  • Public HTTP for external clients or humans -> REST (or REST+JSON). Simple, cacheable, works in every language and tool. Default choice.
  • Rich graph queries with client-driven field selection -> GraphQL. Good when clients need flexible queries and would otherwise build N endpoints.
  • Internal service-to-service with strong typing and streaming -> gRPC. Great for high-throughput internal RPC; bad for browsers and humans.
  • Real-time bidirectional updates -> WebSocket (or SSE for one-way). Pair with a REST/GraphQL API for the non-realtime parts.
  • Just a webhook endpoint -> REST POST with signature verification. Document the signature scheme, payload schema, and retry behavior.
  • Not sure -> ask the user about clients, use cases, and whether humans will consume it. Default to REST when in doubt.

Design flow

1. Understand the shape of the problem

Before picking a protocol or drawing endpoints, ask (use AskUserQuestion for the non-obvious ones):

1. Who calls this API? Browsers, mobile apps, other services, third parties, oncall humans with curl?
2. What are the core resources or operations? Nouns for REST ("orders", "customers"), verbs for RPC-style.
3. Read vs write ratio? Shapes caching and consistency choices.
4. Trust level of callers? Public internet? Authenticated users? Trusted internal services?
5. Latency and throughput targets? Affects protocol, caching, and whether you need streaming.
6. Is there an existing API style the client follows? Consistency with a sibling service is worth a lot.

2. Pick the protocol — and say why in plain English

Write the protocol choice with a one-paragraph justification. A weak reader should understand why without knowing the trade-offs in advance. Example:

REST over HTTPS with JSON payloads. Chosen because the primary clients are the storefront web app (browser) and a third-party partner dashboard, both of which work best with standard HTTP tooling and caching. GraphQL was considered but would add a server-side schema layer for no current benefit.

3. Model the resources (REST)

List resources and operations. Keep it simple:

Conventions to pick once and stick to:

• URL style: lowercase kebab or snake case, plural nouns (/orders, not /order)
• Verbs: POST for create, GET for read, PATCH for partial update, PUT for full replace (rare), DELETE. Sub-actions (like "refund") are POSTs on a sub-path.
• IDs: prefixed ULIDs (ord_abc123) as strings, never integers
• Casing in JSON: snake_case for public APIs, camelCase for internal
• Nested resources: at most one level deep (/customers/:id/orders — flatten beyond that)

See references/http-conventions.md for the full set of HTTP conventions with explanations.

4. Model the operations (GraphQL / gRPC)

GraphQL: define types, queries, mutations, subscriptions in SDL. Every type, field, and argument gets a description string — the schema is the documentation.

gRPC: write the .proto file. Group related RPCs into services. Document each RPC with what it does and what errors it returns.

See references/examples.md for full examples in all three protocols.

5. Define schemas

For each endpoint/operation:

• Request schema — path params, query params, body
• Response schema — success shape and all error shapes
• Constraints — lengths, ranges, allowed values

Use Zod for internal services, OpenAPI for external REST, GraphQL SDL for GraphQL, proto for gRPC.

6. Address cross-cutting concerns

For each of these, apply conventions from the reference files and document any deviation in the spec:

• Authentication — who is the caller? Bearer token, session cookie, API key, mTLS?
• Authorization — what is the caller allowed to do? ABAC enforced at middleware + service layer + RLS.
• Error format — RFC 7807 Problem Details everywhere:

{
  "type": "https://api.example.com/errors/order.read.not_found",
  "title": "Order not found",
  "status": 404,
  "detail": "No order with that ID exists.",
  "instance": "/v1/orders/ord_abc123",
  "request_id": "req_f00b4r"
}

• Pagination — cursor-based default. { data, meta: { next_cursor, has_more } }. Max 100, default 25.
• Idempotency — Idempotency-Key header on all write endpoints.
• Rate limiting — per-plan via DO counters. 429 with Retry-After.
• Versioning — URL path /v1/. Deprecation headers.
• Nullable vs missing — missing = "not provided", null = "explicitly no value".
• CORS — explicit allowlist per environment. Never * with credentials.

For details and rationale on each, see the reference files below.

7. Write the spec

Output to .context/architecture/api/<service>.md. Structure:

1. Summary — one paragraph: what the API does, who calls it, protocol choice + why
2. Base URL and environments — prod, staging, local
3. Authentication — scheme, how to get a token, token lifetime, refresh
4. Conventions — casing, ID format, pagination style, error format, idempotency key header, rate limit headers
5. Resources / operations — each endpoint with request/response schemas and examples
6. Error codes — table of code -> meaning -> when it fires
7. Versioning policy — what's breaking, what isn't
8. Glossary — plain-language definitions of every term a junior wouldn't know

8. Link it up

• Add a link from any related design doc in .context/architecture/
• If the API is for a new service, suggest writing ADRs (documentation:write-adr) for non-obvious choices when available
• If there's a diagram, make sure it matches (workflow:c4-diagrams) when available

Writing principles

Write specs for juniors and weaker LLM models. A spec that only a senior can read is a spec that will be misimplemented:

• Explain every choice in plain language next to the choice. Not just "cursor pagination" — "cursor pagination (clients pass an opaque string and get back the next one; stays stable when items are inserted between requests)".
• Expand jargon on first use. mTLS, JWT, CORS, CSRF — all get a one-line gloss the first time.
• Show examples for every endpoint. A curl example + JSON sample beats a schema table.
• Say why every constraint exists. "Max page size 100 because responses over ~1 MB cause mobile clients to time out."

Cross-references

Key references