APIs: REST, gRPC, WebSockets
How to design APIs that last: REST, gRPC and GraphQL compared, real-time with WebSockets and SSE, cursor pagination, idempotency keys and versioning.
On this page
- The problem: a payment request that timed out
- The idea: an API is a contract between programs
- REST: resources and verbs
- gRPC and GraphQL
- Real-time: polling, SSE and WebSockets
- Pagination: offset vs cursor
- Idempotency keys: making POST safe to retry
- Versioning: changing the contract without breaking clients
- When not to use each
- In the interview
- Quiz
The problem: a payment request that timed out
A mobile app sends POST /payments to charge a customer $40. The phone is on a train; the connection drops before the reply arrives. Did the charge happen? The app doesn't know. If it retries, the customer may pay twice. If it doesn't, the order may never be paid.
The same app has other API troubles: its order history endpoint gets slower the further back users scroll, the chat screen asks the server "anything new?" every 3 seconds, and last month a renamed JSON field broke every older app version still installed on users' phones.
None of these are about choosing the "best" protocol. They are about designing the contract: how requests are named, retried, paged, pushed and changed over time.
The idea: an API is a contract between programs
REST: resources with addresses, verbs and status codes
- An API is a menu of requests one program offers to another: “give me order 42”, “create a new order”, “cancel order 7”. Apps, websites and services all talk through APIs.
- The most common style is REST. Things get web addresses, like slash orders slash 42, and the action is a verb: GET reads, POST creates, PUT updates, DELETE removes.
- Every reply carries a status code: 200 means OK, 201 created, 404 not found, 429 too many requests, 500 something broke on the server. The data itself usually comes back as JSON.
An API (application programming interface) is the set of requests one program accepts from another and the replies it promises. Once other teams or apps depend on it, it is hard to change, so the design matters more than the implementation behind it.
REST: resources and verbs
REST models the system as resources with URLs (/orders/42) and uses HTTP methods as verbs. Replies carry a status code and, usually, JSON.
| Method | Meaning | Safe to retry? |
|---|---|---|
GET /orders/42 | Read | Yes: reading twice changes nothing |
PUT /orders/42 | Replace with this full version | Yes: setting the same thing twice gives the same result |
DELETE /orders/42 | Remove | Yes: the second time, it's already gone |
POST /orders | Create (the server picks the id) | No: two calls create two orders |
PATCH /orders/42 | Partial change | Depends ("add 1 to quantity" isn't) |
A request is idempotent if repeating it has the same effect as doing it once. That column is why the payment problem above exists: POST is not idempotent by default.
The status codes to know: 200 OK, 201 Created, 204 No Content, 400 Bad Request (client sent nonsense), 401 Unauthenticated, 403 Forbidden, 404 Not Found, 409 Conflict (e.g. version mismatch), 429 Too Many Requests (see rate limiting), 500 server error, 503 Service Unavailable (overloaded or down; try later).
POST /v1/orders HTTP/1.1
Content-Type: application/json
Idempotency-Key: 3f2c9a1e-8b7d-4c55-9d3e-2a6b1f0c7e44
{"items": [{"sku": "TSHIRT-M", "qty": 2}], "address_id": 981}
HTTP/1.1 201 Created
Location: /v1/orders/7731
{"id": 7731, "status": "pending", "total_cents": 4000}
gRPC and GraphQL
gRPC: binary messages and a shared contract between services
- Between your own services, many teams use gRPC: compact binary messages and a strict, shared contract. It is faster and catches mistakes early, but it is harder to poke at from a browser.
gRPC defines services and messages in a .proto file (Protocol Buffers), generates client and server code in many languages, and sends compact binary messages over HTTP/2, which carries many requests on one connection at once. It supports streaming in either or both directions and deadlines that travel with the request. Browsers can't speak native gRPC directly; they need gRPC-Web and a proxy, which is why gRPC lives mostly between internal services.
GraphQL exposes one endpoint and a typed schema; the client sends a query naming exactly the fields it wants, possibly across related objects, and gets exactly that shape back. It solves over-fetching (getting fields you don't need) and under-fetching (needing five calls to build one screen), which matters for mobile apps with many screens.
| Style | Good at | Weak at | Use when |
|---|---|---|---|
| REST + JSON | Universal, readable, HTTP caching and CDNs work naturally | Over/under-fetching; loose contracts unless you add OpenAPI | Public APIs, simple CRUD, anything browsers call directly |
| gRPC | Small payloads, generated typed clients, streaming, deadlines | Not browser-native; binary is harder to debug by hand | Service-to-service calls inside your system |
| GraphQL | Clients fetch exactly what a screen needs in one round trip | HTTP caching is harder; expensive queries need cost limits; N+1 resolver problem | Many clients (web, iOS, Android) with different needs over a rich data graph |
Real-time: polling, SSE and WebSockets
Polling wastes requests; a WebSocket lets the server push
- REST and gRPC are request and response: the client must ask. So how does a chat app learn about a new message? With polling, it asks “anything new?” every few seconds. Usually the answer is no: wasted requests, and messages arrive late.
- A WebSocket keeps one connection open in both directions. The server can push a new message the instant it arrives: no wasted asking, no delay.
Request–response APIs only answer when asked. For live updates there are four options:
| Technique | How | Good at | Catch |
|---|---|---|---|
| Short polling | Ask every N seconds | Trivial; works everywhere | Up to N seconds late; most requests return nothing |
| Long polling | Server holds the request open until there's news (or ~30 s) | Near-instant without new protocols | One held request per client; reconnect after each message |
| Server-Sent Events (SSE) | One HTTP response that stays open; the server writes events down it | Simple one-way push; browser reconnects automatically and resumes with Last-Event-ID | Server → client only; text only |
| WebSocket | Upgrades an HTTP connection to a persistent two-way channel | Two-way, low overhead per message | Stateful connections: load balancing, reconnects and fan-out across servers are your problem |
Pick SSE for notifications, live scores and streaming AI responses (server talks, client listens). Pick WebSockets for chat, multiplayer games and collaborative editing (both sides talk often).
Pagination: offset vs cursor
A list endpoint must return results in pages. Two designs:
-- Offset: "page 5,000"
SELECT * FROM orders WHERE customer_id = 42
ORDER BY created_at DESC LIMIT 20 OFFSET 100000;
-- Cursor (keyset): "the 20 after the last one I saw"
SELECT * FROM orders WHERE customer_id = 42
AND (created_at, id) < ('2026-10-03 12:00:00', 88123)
ORDER BY created_at DESC, id DESC LIMIT 20;
Offset (?page=5000) | Cursor (?after=eyJ0Ijo…) | |
|---|---|---|
| Cost of deep pages | Database reads and throws away 100,000 rows | Constant: an index seek to the cursor, then 20 rows |
| New rows arriving while paging | Items shift: duplicates or skipped items | Stable: continues after the last item seen |
| Jump to page 37 | Yes | No, only next/previous |
| Use for | Small admin tables, "page 1–10" UIs | Feeds, timelines, any large or changing list, public APIs |
The cursor is the sort key of the last item (here created_at plus id as a tie-breaker), encoded as an opaque string so clients can't depend on its format. It needs an index on (customer_id, created_at, id) to be fast.
Idempotency keys: making POST safe to retry
Back to the payment on the train. The fix is an idempotency key: the client generates a unique id (a UUID) for each intended operation and sends it with every attempt. The server records the key with the result:
- Look up the key. If it exists with a stored response, return that response: no second charge.
- If it doesn't exist, insert it (a unique constraint on the key prevents two concurrent attempts both proceeding), do the work, store the response, in one transaction where possible.
- If the same key arrives with a different request body, reject it (422 or 409): it's a client bug.
- Expire keys after a window that covers realistic retries (Stripe keeps them at least 24 hours).
Network failures, client retries and load balancer retries all become harmless. This pattern is covered in depth in duplicates and idempotency.
Versioning: changing the contract without breaking clients
Old mobile apps live on phones for years, so you can't change a response in a way that breaks them.
- Additive changes are safe: new optional fields, new endpoints, new enum values (if clients were written to ignore unknown ones).
- Breaking changes: removing or renaming a field, changing a type or meaning, making an optional field required. These need a new version.
- Where the version lives: in the path (
/v1/orders, simplest and most common), in a header (Accept: application/vnd.shop.v2+json), or by date (Stripe pins each account to an API version date). - Retiring a version: measure who still calls it, announce a date, send
DeprecationandSunsetheaders, then remove it.
gRPC and Protocol Buffers bake in a similar rule: never reuse a field number, and add fields rather than changing them.
Designing a good REST resource
Use plural nouns (/orders, /orders/42/items), not verbs (/createOrder). Actions that don't fit CRUD can be sub-resources (POST /orders/42/cancellation). Return 201 with a Location header on create. Use ETags for caching (If-None-Match → 304 Not Modified) and for safe concurrent edits (If-Match → 412 Precondition Failed if someone else changed it first). Put filters in query parameters (/orders?status=paid), and return errors in a consistent body such as RFC 9457 problem details (type, title, detail).
When not to use each
- Not REST for chatty, high-volume internal calls where payload size and typed contracts matter: use gRPC.
- Not gRPC for a public API consumed by unknown developers and browsers.
- Not GraphQL for a simple service with one client, or when CDN caching of responses is your main scaling tool.
- Not WebSockets when updates are rare (polling every minute is fine) or only flow server → client (SSE is simpler).
In the interview
Design the API for a food delivery app: customers browse restaurants near them, place an order, pay, and watch the courier's location live. List the endpoints, the protocol for each, and the two or three design details that matter most.
Compare with our answer
GET /v1/restaurants?lat=..&lng=..&cursor=..: REST, cursor pagination, cacheable for a short time.POST /v1/orderswith an Idempotency-Key: returns 201 and the order id; retries never create two orders.POST /v1/orders/{id}/paymentwith its own idempotency key; returns 202 if the payment provider confirms asynchronously.GET /v1/orders/{id}: status, with ETag.- Live courier location: SSE or WebSocket stream
/v1/orders/{id}/tracking, server → client every few seconds. SSE suffices because the client only listens. - Between internal services (orders, dispatch, payments): gRPC with deadlines.
A strong answer mentions: idempotency keys on order and payment creation · cursor pagination for lists · a push channel for live location, with a reason for SSE vs WebSocket · versioned paths · gRPC internally.
An API offers GET /feed?page=N (offset pagination, newest first), POST /transfer with no idempotency key, and a v1 response field user_name that the team wants to rename to username. Users report seeing the same posts twice while scrolling, and one double transfer. What is wrong and how would you fix each?
Compare with our answer
- Duplicates while scrolling: new posts arrive at the top, shifting everything down, so page N+1 repeats items from page N. Switch to cursor pagination on
(created_at, id). - Deep pages slow: offset makes the database skip all earlier rows; cursors seek directly.
- Double transfer:
POSTwithout a key is not idempotent; a timeout plus retry charged twice. Require anIdempotency-Key, store key → response with a unique constraint, and reject a reused key with a different body. - Renaming a field breaks older clients. Add
usernamealongsideuser_name, mark the old one deprecated, measure usage, and remove it only in/v2or after a sunset date.
A strong answer mentions: why offset pages shift · cursor on a unique sort key · idempotency key with a unique constraint and stored response · additive change plus deprecation instead of a rename · version bump for breaking changes.
- REST: resources + HTTP verbs. GET, PUT, DELETE are idempotent; POST isn't. Know 200/201/400/401/403/404/409/429/500/503.
- gRPC: protobuf + HTTP/2, typed generated clients, streaming, deadlines. Internal service calls.
- GraphQL: client chooses fields; fixes over/under-fetching; watch N+1 (batch loaders) and query cost.
- Real-time: polling (simple, late) · long polling · SSE (one-way, auto-reconnect) · WebSocket (two-way, stateful).
- WebSockets at scale: connection registry, pub/sub between servers, reconnect with backoff, drain on deploy.
- Pagination: cursor (keyset) for large or changing lists; offset only for small tables.
- Idempotency key: client UUID per operation; server stores key → response under a unique constraint; ~24 h.
- Versioning: additive changes only;
/v1in the path; deprecate with headers and a sunset date.
1. A mobile app's POST /payments sometimes times out, and the app retries. Some customers are charged twice. What is the best fix?
An idempotency key lets the server recognise a retry and return the original result. A longer timeout or delay reduces the chance but never removes it, and PUT is only idempotent if it really replaces a resource by a client-chosen id.
2. An activity feed uses ?page=N with newest items first. Users scrolling down see some posts twice. Why, and what fixes it?
With offsets, items inserted at the top push earlier items onto the next page. A cursor continues from the last item seen, so inserts don't shift anything.
3. Two internal services exchange 50,000 small messages per second and are owned by different teams that want a strict contract. Which fits best?
Internal, high-volume, typed contracts across teams: gRPC's strengths. REST works but is larger and looser; GraphQL and WebSockets solve different problems.
4. A sports site wants to push live scores to millions of browsers. Clients never send anything back on that channel. Which is the simplest good choice?
SSE is built for one-way server push over HTTP, with automatic reconnection. WebSockets also work but add two-way machinery that isn't needed; browsers can't speak native gRPC.
5. A team wants to rename the JSON field user_name to username in their public API. What is the safest approach?
Additive changes don't break old clients. Removing or renaming a field does, so it belongs in a new version after a deprecation period.
6. A GraphQL query fetches 100 posts with their authors, and the server makes 101 database queries. What is the standard fix?
This is the N+1 problem. A batching loader (DataLoader) collects the ids and runs one query. Caching hides it partly; smaller pages only shrink it.
7. Which request is idempotent as written?
Setting the email to the same value twice has the same effect as once. Creating, adding or depositing changes state again on every repeat.
Score 60% or more and the lesson is marked complete.