System design · Concept 9

API Design

Choosing REST, gRPC, GraphQL, WebSockets or SSE, plus pagination, versioning, idempotency keys and authentication basics.

7 min read

In short

  • REST or GraphQL at the edge, gRPC inside, SSE or WebSockets for real-time
  • Methods and status codes used precisely
  • Cursor pagination for large or live lists
  • Idempotency keys on retried writes
  • Authorize per resource in the owning service

The API is the contract the rest of the system depends on, and it's the hardest part to change later. In a design discussion, a crisp API shows you understand the problem: what the operations are, what they take and return, and how they behave under retries, large result sets and change.

Choosing a style

StyleTransport / formatStrengthsWeaknessesTypical use
RESTHTTP/1.1-2, JSONUniversal, cacheable GETs, simple toolingOver/under-fetching, chatty for complex screensPublic APIs, CRUD, most web backends
gRPCHTTP/2, ProtobufFast, typed contracts, streaming, codegen, deadlinesNot browser-native (needs grpc-web), binary is harder to debugInternal service-to-service, mobile with strict perf
GraphQLHTTP, JSONClient picks fields, one round trip per screen, strong schemaCaching is harder, N+1 queries, query cost control neededAggregating many backends for varied UI clients (BFF)
WebSocketsPersistent TCP, bidirectionalReal-time both ways, low overhead per messageStateful connections, scaling/LB complexityChat, multiplayer, collaborative editing
SSEHTTP, server → client streamSimple, auto-reconnect, works through proxiesOne direction only, text onlyLive feeds, notifications, progress, LLM token streaming
Long pollingHTTPWorks everywhereLatency + overhead per messageFallback for real-time
WebhooksHTTP callbacks to the client's serverPush events to partnersDelivery retries, security (signatures)Payment status, integrations

A common setup: REST (or GraphQL BFF) at the edge, gRPC or messaging inside, WebSockets/SSE for real-time.

REST essentials

  • Resources as nouns, operations as methods: GET /orders/42, POST /orders, PATCH /orders/42, DELETE /orders/42.
  • Nest only where ownership is real: /users/7/orders. Don't go deeper than two levels.
  • Actions that don't map cleanly to CRUD can be sub-resources: POST /orders/42/cancel.
MethodSafeIdempotentTypical response
GETYesYes200
PUT (full replace)NoYes200 / 204
DELETENoYes204
PATCHNoNot inherently200
POSTNoNo, so use an idempotency key201 + Location, or 202
StatusMeaning
200 / 201 / 202 / 204OK / created / accepted for async processing / no content
400 / 422Malformed / semantically invalid
401 / 403Not authenticated / not allowed
404 / 409Not found / conflict (version mismatch, duplicate)
429Rate limited (send Retry-After)
500 / 503Server error / temporarily unavailable

Return errors in a consistent format, e.g. RFC 9457 problem details: { "type", "title", "status", "detail", "instance" }.

Real-time options

WebSocketsSSELong polling
DirectionBothServer → clientServer → client (client re-requests)
LatencyLowestLowMedium
InfraSticky, stateful gateways, L4/L7 with upgrade supportPlain HTTP, easy behind proxies/CDNsPlain HTTP
ReconnectDIY (backoff, resume token)Built in (Last-Event-ID)Natural
Pick whenClient sends frequently too (chat, games)Client mostly listens (notifications, dashboards)Constrained environments

Pagination

Offset pagination: GET /posts?offset=40&limit=20 → OFFSET 40 LIMIT 20

  • Simple, and lets users jump to page N.
  • Slow for deep pages (the DB still scans and discards the offset rows).
  • Unstable: inserts and deletes shift items between pages (duplicates or gaps).

Cursor (keyset) pagination: GET /posts?limit=20&cursor=eyJ0IjoiMjAyNi0xMC0xN1QxMDowMDowMFoiLCJpZCI6OTg3fQ

-- cursor decodes to the last item seen: (created_at, id)
SELECT * FROM posts
WHERE (created_at, id) < ($cursor_created_at, $cursor_id)
ORDER BY created_at DESC, id DESC
LIMIT 20;
  • Constant-time per page via the index, and stable while data changes.
  • No random page jumps.
  • Make the cursor opaque (base64 of the sort key), include a tie-breaker (id), and return nextCursor (null at the end).
  • Use cursors for feeds, timelines, logs and any large or changing list. Use offsets for small admin tables.

Versioning and evolution

ApproachExampleNotes
URL path/v1/ordersMost visible and common for public APIs
HeaderApi-Version: 2026-10-01Date-based versions (Stripe style) allow fine-grained evolution
Media typeAccept: application/vnd.acme.v2+jsonPrecise but less discoverable
  • Prefer additive changes: new optional fields and new endpoints. Clients must ignore unknown fields.
  • Breaking changes (removing or renaming fields, changing types or semantics) need a new version, a deprecation window, Deprecation/Sunset headers and usage metrics on the old version.
  • For Protobuf: never reuse field numbers, and mark removed ones reserved.

Idempotency keys

Clients retry on timeouts, and without protection a retried POST /payments charges twice.

POST /v1/payments
Idempotency-Key: 5d1c7a8e-...        (client-generated UUID per logical operation)
{ "orderId": "o_123", "amount": 4999, "currency": "USD" }

Server behavior:

  1. Look up the key (scoped per client/account).
  2. New → store {key, requestHash, status: in_progress} atomically, process, then store the response.
  3. Seen, completed → return the stored response unchanged.
  4. Seen, in progress → 409 Conflict (or wait briefly).
  5. Same key, different payload → 422. That's a client bug.
  6. Expire keys after a window (e.g. 24 h-7 days).

Authentication and authorization basics

MechanismUse forNotes
Session cookieFirst-party web appsHttpOnly, Secure, SameSite; CSRF protection
OAuth 2.0 + OIDCUser login, delegated access, SSOAuthorization code + PKCE for SPAs/mobile; identity provider (Cognito, Entra ID, Identity Platform, Auth0, Keycloak)
JWT access tokenStateless API authShort-lived (5-15 min), verify signature + exp/aud/iss; refresh tokens for renewal
Opaque tokenWhen revocation mattersIntrospect or look up (cache it)
API keyServer-to-server, partner/developer APIsHash at rest, scope, rotate; identify the caller for rate limits
mTLS / workload identityInternal service-to-serviceService mesh issues certs automatically
HMAC signaturesWebhooksSign payload + timestamp; verify and reject replays
  • Authentication answers who you are. Authorization answers what you may do: RBAC (roles) or ABAC/ReBAC (attributes, relationships like "editor of this folder").
  • Validate tokens at the gateway for coarse checks, and enforce resource-level authorization in the service that owns the data.
  • Never trust client-provided IDs for ownership. Check resource.ownerId == token.sub or the ACL.

Other details that signal experience

  • Rate limit headers: RateLimit-Policy and RateLimit (the IETF draft; many APIs still send the older X-RateLimit-Limit/-Remaining/-Reset), and Retry-After on 429.
  • Conditional requests: ETag + If-None-Match (cache revalidation, 304), If-Match (optimistic concurrency, 412).
  • Long-running operations: 202 Accepted + Location: /operations/123, then poll or receive a webhook.
  • Batch endpoints to avoid chatty clients, with per-item results.
  • Large uploads/downloads: pre-signed object storage URLs instead of proxying bytes through your API.
  • Field selection / sparse fieldsets and compression for mobile clients.

When to use / trade-offs

  • REST by default for external and CRUD APIs. It's simple and cacheable, but can be chatty.
  • gRPC for internal high-throughput calls with strict contracts. You need extra tooling for browsers and debugging.
  • GraphQL when many client types need different shapes of the same data. You pay in caching complexity and resolver performance work.
  • WebSockets only when you need bidirectional real-time traffic. Stateful connections complicate scaling and deploys. SSE is often enough.
  • Cursor pagination over offset for anything large or live.
  • Version sparingly: additive evolution beats maintaining v1, v2 and v3 in parallel.

Checklist

  • Style chosen per client and per hop (edge vs internal vs real-time)
  • Resources, methods, status codes and error format defined
  • Cursor pagination for large/live lists
  • Idempotency keys on retried non-idempotent writes
  • Versioning and deprecation strategy
  • Authentication method, token lifetime, and resource-level authorization
  • Rate limits, async operations, large payloads via pre-signed URLs

Practise this concept

In the app: a short video and a 11-question concept check. Free with a GitHub account.

Open in the app