The API Surface

You've consumed thousands of APIs. You know the pain of one that returns different shapes for the same thing, or makes you call it five times to render one screen. This chapter is about being on the other side of that and not inflicting the same pain on the next developer.

REST, done right

REST isn't a protocol. It's a set of conventions for using HTTP consistently. The core ideas:

• Resources are nouns, named by URLs: /users, /orders/42.
• Verbs are HTTP methods: GET reads, POST creates, PUT replaces, PATCH partially updates, DELETE removes.
• GET is safe (no side effects) and idempotent (calling it many times is the same as once). PUT and DELETE are idempotent but not safe. POST is neither.

A clean set of routes for one resource looks like this:

Keep your error responses consistent too. The application/problem+json standard gives you one shape for every error: a title, a status, a human-readable detail, and a type the client can branch on. One shape everywhere beats a different error body per endpoint.

On versioning, the most common option is putting the version in the URL (/v1/users). It's not clever, and that's the point. The real discipline isn't the strategy, it's the promise: once a version is public, you add fields but never remove them. Deprecate, announce a date, then retire.

REST vs GraphQL vs tRPC vs gRPC

Authentication, from the protocol level

Authentication answers "who are you." Two approaches dominate.

Sessions. The server stores a session (user ID, expiry) and hands the client an opaque ID, usually in a cookie. The client sends it back each request; the server looks it up. Easy to revoke (delete the row), but the server has to store and look up every session.

JWT. A self-contained token: header, payload, signature. The payload holds user info, the signature proves the server issued it. The server verifies it without storing anything. That's the strength and the weakness, because a JWT can't be revoked before it expires unless you build a blocklist, which removes the statelessness. The usual pattern is a short-lived access token (15 minutes) plus a long-lived refresh token you can rotate and revoke.

For "log in with Google," you want OAuth 2.1 with OIDC on top for identity. The flow most apps use is Authorization Code with PKCE. Don't build it from scratch. Use a library or a provider (this very site uses Clerk).

Authorization, beyond if-statements

Authorization answers "what are you allowed to do." Three models, increasing in power:

• RBAC (role-based). Users have roles (admin, editor, viewer), roles have permissions. Simple and fine for many apps. It struggles with "user X can edit document Y because they own it," which is per-resource.
• ABAC (attribute-based). Decisions weigh attributes of the user, the resource, and the environment. Powerful, but the policy grows fast.
• ReBAC (relationship-based). Decisions follow a graph: this user is in this team, that team owns this project, that project holds this document. Google's Zanzibar paper popularised it.

Pagination, properly

Return something like { data: [...], nextCursor: "...", hasMore: true }. Skip the total count unless the client truly needs it, because counting is often slower than paging.

Idempotency

An operation is idempotent if doing it twice has the same effect as doing it once. GET is naturally idempotent. POST is not, unless you make it so.

Why it matters: networks fail. A client posts an order, the server processes it, the response is lost, the client retries. Without idempotency, you just charged the customer twice.

The standard fix is an idempotency key: the client generates a unique ID per operation and sends it in a header. The server stores the result under that key and replays it on a retry instead of running the operation again. Here's the whole idea in a few lines.

You'll almost never get exactly-once delivery over a network. What you get is at-least-once delivery plus idempotent handlers, which adds up to the same thing in practice.

Rate limiting

A single user with a script can hammer your API. A token bucket is the standard defence: each user gets a bucket that refills over time, a request costs a token, and an empty bucket means a 429. For multiple server instances the counter has to live somewhere central, which is where Redis comes in. Here's the bucket itself.

Real-time: WebSockets, SSE, long polling

Three transports for pushing data to a client:

Long polling (hold a request open until there's something to send) still works through every proxy, but it's high-overhead and mostly a fallback now.

The easy demo isn't the hard part. The hard parts are presence (who's online, usually a heartbeat with a TTL in Redis), reconnection (clients drop and need to catch up on what they missed), and fanout (one event reaching many subscribers, which needs a broker like Redis or NATS once you're on more than one process).

Background jobs and queues

Anything that takes more than a couple hundred milliseconds shouldn't happen in the request handler. Sending email, generating a PDF, calling a slow third party: all of it goes to a queue. The handler validates the input, writes a job, and returns. A worker picks it up later.

In Node, BullMQ (Redis-backed) is the common default. Inngest and Temporal offer durable workflows that can retry and even sleep for days.

Jobs fail, so always retry, but carefully: exponential backoff (wait 1s, 2s, 4s) so you don't hammer a struggling service, jitter (a little randomness) so a crowd of retries doesn't all hit at once, and a max attempts cap after which the job goes to a dead-letter queue for a human to look at. And because queues deliver at-least-once, every job handler must be idempotent, the same lesson as the API.