/api-design

name: api-design
description: This skill should be used when the user needs to "design the API", do "endpoint design", pin down a "request/response shape", choose a "pagination" strategy (cursor vs offset), add an "idempotency key" to a write, plan "API versioning", an "error contract", or pick between "REST vs gRPC vs GraphQL" or "WebSocket vs polling". Use it whenever a design has reached the interface — the concrete request, response, primary access path, and how clients page, retry, and version — even if the user only said "the boxes talk to each other".

API Design

Define the contract between clients and a service: the exact request and response shapes, how callers page through data, how retried writes stay safe, how errors are reported, and how the contract evolves. Get this vague and the rest of the diagram is guesswork (GUIDE #8) — a "NoSQL box" or "user service" solves nothing until you can write the request, the response, and the key it hits.

When to reach for this

The design has named services and a datastore, and you now need the *interface*: what a client sends, what it gets back, how it fetches the next page, how it retries a payment without double-charging, and how a v1 client survives a v2 deploy. Reach here the moment someone says "fetch the feed" or "store the post" without a shape.

When NOT to

Before requirements and scale are pinned — the protocol choice depends on read/write ratio and latency target, not taste (→ `requirements-scoping`, `back-of-the-envelope`). Don't reach for gRPC, GraphQL, or streaming because they sound modern; a plain REST/JSON endpoint is the cheapest contract that meets most constraints, and naming a fancier protocol you don't need is a YAGNI red flag. Internal data-access keys and partition design live in `data-storage`; this skill designs the *external* contract that mirrors them.

Clarify first

• **Call shape** — request/response (CRUD), bidirectional/real-time, or one

request → many results (streaming)? This picks the protocol.

• **Read/write ratio and result-set size** — drives pagination and whether reads

need their own optimized path (→ `back-of-the-envelope`).

• **Retry safety** — can a write be safely repeated? Which operations are

naturally idempotent (PUT/DELETE) vs not (POST that creates/charges)?

• **Client diversity & churn** — public third parties (slow to upgrade, need

strict versioning) vs your own apps (ship together)?

• **Latency & payload budget** — mobile/high-latency links favor compact binary

and fewer round trips; browsers favor cacheable HTTP.

The options

**Protocol / style** (pick per call shape)

• **REST over HTTP/JSON** — resource CRUD over standard verbs. Use as the default

for public, cacheable, browser-friendly APIs.

• **RPC / gRPC (HTTP/2, protobuf)** — typed method calls, compact binary,

streaming. Use for internal service-to-service traffic where latency and schema contracts matter.

• **GraphQL** — client specifies exactly the fields it wants in one query. Use

when many clients need different shapes of the same graph and over/under-fetching on REST hurts.

• **WebSocket / SSE (streaming)** — persistent server→client push. Use when the

server must push updates (chat, presence, live feeds) — see the polling tier below.

• **Webhooks** — server calls *the client's* URL on an event. Use for async,

third-party event delivery.

**Server-push tier** (when clients need fresh data)

• **Polling** → **long-polling** → **SSE** → **WebSocket**, in increasing

efficiency for push and increasing connection cost. Start at polling; escalate only when a number (update frequency, fanout) forces it.

**Pagination**

• **Cursor (keyset)** — opaque token over a stable sort key. Default for large or

changing datasets.

• **Offset/limit** — `?offset=40&limit=20`. Use only for small, mostly-static,

jump-to-page lists.

**Idempotency** — client sends an `Idempotency-Key` on unsafe writes; the server dedupes retries. This skill owns the key contract (see Interface sketch).

**Versioning** — URI (`/v2/...`), header (`Accept: application/vnd.x.v2+json`), or additive/never-break. Prefer additive; reserve a new version for breaking changes.

Trade-offs

| Option | What it solves | What it worsens | Change it when | |---|---|---|---| | REST/JSON | Universal, cacheable, simple, tooling everywhere | Over/under-fetch; chatty for graphs; weak typing | Field-shaping pain → GraphQL; internal latency → gRPC | | gRPC/RPC | Compact, typed, fast, native streaming | Not browser-native; needs proxy; opaque to HTTP caches | Public/browser clients need it → REST gateway | | GraphQL | One round trip, client picks fields | Caching/rate-limiting hard; expensive queries (N+1); server complexity | Few fixed shapes (REST simpler) or query cost unbounded | | WebSocket/SSE | True server push, low-latency updates | Stateful connections, harder to scale/LB, reconnection logic | Updates are infrequent → long-poll; one-way only → SSE | | Cursor pagination | Stable under inserts; O(1) per page at any depth | Opaque token; no random page jump; needs sort key | Users must jump to page N of a static set → offset | | Offset pagination | Trivial; arbitrary page jumps | Drift/dupes on insert; deep offsets scan & slow | Set grows or mutates → cursor | | Idempotency keys | Safe retries; no double-charge | Server must store keys + dedupe; key TTL/scope to define | Op is naturally idempotent (PUT/DELETE) → may skip | | URI versioning | Explicit, cache/log-visible, easy to route | Version sprawl; clients pinned forever | Changes are additive → no new version needed |

Behavior under stress

The contract decides how badly a client *amplifies* an incident.

• **Retry storms.** A timed-out write that isn't idempotent gets retried and may

double-execute; clients retrying in lockstep stampede a recovering service. Idempotency keys make retries safe; the backoff/jitter that *paces* them is owned by `resilience-failure`. S