API design — REST, idempotency, versioning

"Design the endpoints for X" shows up in mid/senior loops. They want resource modeling, correct verbs and status codes, and awareness of idempotency + pagination + versioning.

First, the vocabulary — every term you need, defined once

Before any design, lock down the words. None of these are hard once you see them in plain English, but interviewers notice when you use them precisely. Read this list once and the rest of the lesson is just applying it.

• API — a contract for talking to a program over the network. A web API speaks HTTP (HyperText Transfer Protocol — the request/response protocol the web runs on) and usually trades JSON (a plain-text data format of keys and values, e.g. {"id":7}).
• REST (Representational State Transfer) — a design style: model your system as resources addressed by URLs, and act on them with the standard HTTP verbs. It is a convention, not a library you install.
• Resource — a "thing" your system owns that has an identity: a user, an order, an invoice. Each has a URL (e.g. /users/42). A collection is the plural URL holding many of them (/users).
• HTTP method (verb) — the action: GET read, POST create, PUT replace, PATCH partial-update, DELETE remove.
• Status code — the server's 3-digit verdict. 2xx = it worked, 3xx = go look elsewhere, 4xx = you (the caller) made a mistake, 5xx = the server broke.
• Idempotency — doing the same call N times has the same effect as doing it once. GET/PUT/DELETE are naturally idempotent; POST is not.
• Statelessness — the server keeps no memory of you between calls; every request must carry everything needed to handle it (including who you are). This is what lets you put ten identical servers behind a load balancer — any of them can answer any request.
• Pagination — returning a big list in small slices ("pages") instead of all at once. Offset = "skip the first N"; cursor = "give me what comes after this bookmark."
• Versioning — labelling the API (/v1/) so you can change it later without breaking callers who depend on today's behaviour.
• Rate limiting — capping how many calls a client may make per window (e.g. 100/min) to protect the service; over the cap you return 429.
• Authentication (authn) — proving who you are. Authorization (authz) — deciding what you're allowed to do. (Hence 401 vs 403.)
• Schema — the agreed shape of a request or response body: which fields exist, their types, which are required.

A concrete, well-designed resource API

Theory clicks once you see real endpoints. Here is a small but complete design for users and their orders. Notice the pattern: plural nouns for collections, an id in the path to address one item, and nesting to express "belongs to" (an order belongs to a user). The verb — not the URL — says what you're doing, so you never write /createUser or /getUserOrders; the method already carries that meaning.

# Collection of users
GET    /users                 # list users (paginated)        -> 200
POST   /users                 # create a user                 -> 201 + Location: /users/42

# A single user (the {id} is that user's identity in the path)
GET    /users/42              # read one user                 -> 200 or 404
PUT    /users/42              # replace the whole user        -> 200 / 204
PATCH  /users/42              # change only the fields sent   -> 200 / 204
DELETE /users/42              # remove the user               -> 204 or 404

# Orders that BELONG TO a user — nesting shows the relationship
GET    /users/42/orders       # this user's orders (paginated)-> 200
POST   /users/42/orders       # place an order for this user  -> 201
GET    /users/42/orders/9001  # read one order                -> 200 or 404

Now a full create, end to end. The client sends a request (method + URL + headers + JSON body); the server returns a response (status code + headers + JSON body). Note the Idempotency-Key header on the write, and the Location header pointing at the freshly-made resource:

# --- REQUEST ---
POST /users/42/orders
Authorization: Bearer eyJhbGci...        # who I am (a token, see Auth below)
Idempotency-Key: 6f1c-...-a3            # makes retrying this POST safe
Content-Type: application/json
{
  "sku": "BOOK-001",
  "quantity": 2
}

# --- RESPONSE ---
HTTP/1.1 201 Created
Location: /users/42/orders/9001         # URL of the thing just created
Content-Type: application/json
{
  "id": 9001,
  "user_id": 42,
  "sku": "BOOK-001",
  "quantity": 2,
  "status": "pending",
  "created_at": "2026-06-03T10:00:00Z"
}

And a list call, showing pagination and filtering on the same collection. The response wraps the array in an object so there's room for paging metadata next to the data — returning a bare top-level array is a classic trap, because you can never add fields beside it later without breaking clients.

# --- REQUEST ---
GET /users/42/orders?status=pending&sort=-created_at&limit=2

# --- RESPONSE ---
HTTP/1.1 200 OK
{
  "data": [
    { "id": 9001, "status": "pending" },
    { "id": 9000, "status": "pending" }
  ],
  "next_cursor": "eyJpZCI6OTAwMH0",    # pass as ?after=... for the next page
  "has_more": true
}

The error format (one shape, every time)

Pick a single JSON error envelope and use it for every failure, across all endpoints. The key is a stable, machine-readable code that clients can branch on — the human message can be reworded freely, but the code is a promise. Never return a raw stack trace or a bare string; clients can't react to prose, and traces leak your internals.

HTTP/1.1 422 Unprocessable Entity
{
  "error": {
    "code": "INVALID_QUANTITY",        # stable; clients switch on this
    "message": "quantity must be >= 1",   # human-friendly, may change
    "field": "quantity"                  # which input was wrong
  }
}

Authentication: who's calling?

Because REST is stateless, every request must prove its own identity — the server won't remember you from last time. There are three common ways, from simplest to richest:

• API key — a long secret string the caller sends on every request (often Authorization: Bearer sk_live_... or an X-Api-Key header). Simple, great for server-to-server. Downside: one flat secret, easy to leak, all-or-nothing power, awkward to rotate.
• OAuth 2.0 — a protocol for "let app B act on my behalf without handing over my password" (the "Log in with Google" flow). The user approves, and the app receives a scoped, expiring access token. OAuth answers "how do I safely get a token"; it usually hands you a JWT.
• JWT (JSON Web Token) — a token format: a base64 string holding claims (e.g. {"sub":"42","exp":...}) plus a cryptographic signature. The server verifies the signature and trusts the contents without a database lookup — perfect for stateless auth. It says nothing about how you obtained it (that's OAuth's job).

One-line distinction to say out loud: API key = a shared secret; OAuth = the handshake that issues a token; JWT = the shape of the token that handshake hands back.

REST vs GraphQL vs gRPC

REST is the default, but interviewers love the comparison. All three are ways to call a remote server; they differ in who decides the response shape and how it travels.

• REST — many URL endpoints, one per resource; the server decides each response shape. Plays perfectly with HTTP caching, proxies, and browsers. Weakness: a screen needing several resources makes several round-trips, and a fixed shape can over-fetch (send fields you don't need) or under-fetch (force a second call).
• GraphQL — a single endpoint where the client writes a query describing exactly the fields it wants, and the server returns precisely that. Kills over/under-fetching and round-trips. Cost: HTTP caching no longer works for free, and you must guard against expensive client queries (depth/cost limits).
• gRPC — a high-performance scheme using protocol buffers (a compact binary format defined in a .proto schema) over HTTP/2. Fast, strongly-typed, supports streaming — ideal for service-to-service calls inside a backend. Weakness: not browser-friendly without a proxy, and binary payloads are harder to eyeball.

Rule of thumb for the room: REST for public/web-facing CRUD, GraphQL when many clients need wildly different slices of the same data graph, gRPC for chatty internal microservices where speed and typing matter.

Design principles & pitfalls

A handful of principles separate an API that ages well from one that becomes a support burden:

• Be consistent. One naming convention (plural nouns, snake_case or camelCase — pick one), one date format (ISO-8601 UTC), one error envelope, one pagination style. Surprises are bugs.
• Nouns in URLs, not verbs. POST /orders, never /createOrder. The HTTP method is the verb.
• Use the right status code. Don't return 200 with {"error":...} in the body — callers and proxies trust the code. Map failures to the correct 4xx/5xx.
• Make writes idempotent where you can. PUT/DELETE naturally; for POST, accept an idempotency key so retries are safe.