System design · Concept 9
API Design
Choosing REST, gRPC, GraphQL, WebSockets or SSE, plus pagination, versioning, idempotency keys and authentication basics.
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
| Style | Transport / format | Strengths | Weaknesses | Typical use |
|---|---|---|---|---|
| REST | HTTP/1.1-2, JSON | Universal, cacheable GETs, simple tooling | Over/under-fetching, chatty for complex screens | Public APIs, CRUD, most web backends |
| gRPC | HTTP/2, Protobuf | Fast, typed contracts, streaming, codegen, deadlines | Not browser-native (needs grpc-web), binary is harder to debug | Internal service-to-service, mobile with strict perf |
| GraphQL | HTTP, JSON | Client picks fields, one round trip per screen, strong schema | Caching is harder, N+1 queries, query cost control needed | Aggregating many backends for varied UI clients (BFF) |
| WebSockets | Persistent TCP, bidirectional | Real-time both ways, low overhead per message | Stateful connections, scaling/LB complexity | Chat, multiplayer, collaborative editing |
| SSE | HTTP, server → client stream | Simple, auto-reconnect, works through proxies | One direction only, text only | Live feeds, notifications, progress, LLM token streaming |
| Long polling | HTTP | Works everywhere | Latency + overhead per message | Fallback for real-time |
| Webhooks | HTTP callbacks to the client's server | Push events to partners | Delivery 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.
| Method | Safe | Idempotent | Typical response |
|---|---|---|---|
| GET | Yes | Yes | 200 |
| PUT (full replace) | No | Yes | 200 / 204 |
| DELETE | No | Yes | 204 |
| PATCH | No | Not inherently | 200 |
| POST | No | No, so use an idempotency key | 201 + Location, or 202 |
| Status | Meaning |
|---|---|
| 200 / 201 / 202 / 204 | OK / created / accepted for async processing / no content |
| 400 / 422 | Malformed / semantically invalid |
| 401 / 403 | Not authenticated / not allowed |
| 404 / 409 | Not found / conflict (version mismatch, duplicate) |
| 429 | Rate limited (send Retry-After) |
| 500 / 503 | Server error / temporarily unavailable |
Return errors in a consistent format, e.g. RFC 9457 problem details: { "type", "title", "status", "detail", "instance" }.
Real-time options
| WebSockets | SSE | Long polling | |
|---|---|---|---|
| Direction | Both | Server → client | Server → client (client re-requests) |
| Latency | Lowest | Low | Medium |
| Infra | Sticky, stateful gateways, L4/L7 with upgrade support | Plain HTTP, easy behind proxies/CDNs | Plain HTTP |
| Reconnect | DIY (backoff, resume token) | Built in (Last-Event-ID) | Natural |
| Pick when | Client 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 returnnextCursor(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
| Approach | Example | Notes |
|---|---|---|
| URL path | /v1/orders | Most visible and common for public APIs |
| Header | Api-Version: 2026-10-01 | Date-based versions (Stripe style) allow fine-grained evolution |
| Media type | Accept: application/vnd.acme.v2+json | Precise 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/Sunsetheaders 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:
- Look up the key (scoped per client/account).
- New → store
{key, requestHash, status: in_progress}atomically, process, then store the response. - Seen, completed → return the stored response unchanged.
- Seen, in progress →
409 Conflict(or wait briefly). - Same key, different payload →
422. That's a client bug. - Expire keys after a window (e.g. 24 h-7 days).
Authentication and authorization basics
| Mechanism | Use for | Notes |
|---|---|---|
| Session cookie | First-party web apps | HttpOnly, Secure, SameSite; CSRF protection |
| OAuth 2.0 + OIDC | User login, delegated access, SSO | Authorization code + PKCE for SPAs/mobile; identity provider (Cognito, Entra ID, Identity Platform, Auth0, Keycloak) |
| JWT access token | Stateless API auth | Short-lived (5-15 min), verify signature + exp/aud/iss; refresh tokens for renewal |
| Opaque token | When revocation matters | Introspect or look up (cache it) |
| API key | Server-to-server, partner/developer APIs | Hash at rest, scope, rotate; identify the caller for rate limits |
| mTLS / workload identity | Internal service-to-service | Service mesh issues certs automatically |
| HMAC signatures | Webhooks | Sign 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.subor the ACL.
Other details that signal experience
- Rate limit headers:
RateLimit-PolicyandRateLimit(the IETF draft; many APIs still send the olderX-RateLimit-Limit/-Remaining/-Reset), andRetry-Afteron 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