REST & Resource Design

"A good API is like a good joke: if you have to explain it, it isn't that good." — a maxim passed around API design reviews

You have met HTTP — its methods, status codes, and headers — and you have seen that a backend is, at heart, a function from request to response. Now we design the shape of that contract: the URLs your clients call, the verbs they use, the data they get back. This is API design, and REST is the style that has quietly organized the majority of the web's APIs for two decades.

Get this right and your API feels obvious: a frontend engineer guesses the endpoint before reading the docs, a mobile team integrates in an afternoon, and a new hire ships a feature without a meeting. Get it wrong and every screen needs a Slack thread, every field has three casings, and nobody is sure whether POST /deleteUser really deletes. The difference is not cleverness — it is a handful of conventions applied with discipline. By the end of this chapter you will design resource-oriented endpoints, map operations to methods and status codes correctly, and defend your choices in an interview.

REST is a style, not a spec

REST — REpresentational State Transfer — was described by Roy Fielding in his 2000 PhD dissertation, not as a protocol you install but as an architectural style: a set of constraints that, if you honor them, tend to produce systems that are scalable, evolvable, and simple to reason about. It is deliberately built on top of HTTP's existing machinery rather than inventing new machinery.

The single idea at REST's core is this: model your system as resources — the nouns of your domain (a user, an order, a comment) — each identified by a URL, and manipulate them with HTTP's small, fixed set of methods — the verbs (GET, POST, PUT, PATCH, DELETE). You do not invent an operation vocabulary; you reuse HTTP's. GET /users/42 means "read user 42." DELETE /users/42 means "remove user 42." The method says what you're doing; the URL says what you're doing it to.

Naming resources: nouns, plural, hierarchical

The URL is the identity of a resource, and the conventions for naming are near-universal. Follow them and your API will feel familiar to every engineer who has touched a REST API before.

The verb lives in the HTTP method, never in the path. The moment you see POST /users/42/delete or GET /fetchOrders, you are looking at RPC wearing a REST costume. The path names a thing; the method names the action.

Nesting expresses containment. /users/42/orders reads as "the orders belonging to user 42" and is the natural URL for listing or creating within that scope. A useful discipline: nest only one level deep. /users/42/orders/1001/items/3 is technically legal but painful; once an order has its own identity, prefer /orders/1001 and let it carry a userId field. Deep nesting couples URLs to a hierarchy that often changes.

Mapping CRUD to methods and status codes

Most resource operations reduce to CRUD — Create, Read, Update, Delete — and each maps to a method, a URL, and an expected success status code. This table is the backbone of REST API design; internalize it.

A few status codes carry real meaning and are worth getting exactly right:

• 201 Created on a successful POST, ideally with a Location: /users/43 header pointing at the new resource.
• 204 No Content on a successful DELETE (or a PUT/PATCH that returns nothing) — the request worked, there is simply no body to send.
• 400 Bad Request for malformed or invalid input; 422 Unprocessable Entity when the syntax is fine but the semantics fail validation (many teams use one or the other consistently).
• 401 Unauthorized means "not authenticated" (we don't know who you are); 403 Forbidden means "authenticated but not allowed."
• 404 Not Found for a resource that doesn't exist; 409 Conflict for a create that collides (duplicate email) or a version mismatch.

PUT vs PATCH vs POST — the classic confusion

These three are asked in interviews constantly because they are genuinely easy to conflate:

• POST creates a new resource in a collection, or triggers a non-idempotent action. The server usually assigns the id. Calling it twice creates two resources.
• PUT replaces a resource at a known URL with the full representation you send. It is idempotent: PUT /users/42 with the same body ten times leaves the same final state as doing it once. Fields you omit are conceptually cleared.
• PATCH partially updates — you send only the fields that change (e.g. { "email": "new@x.io" }) and leave the rest untouched.

We'll return to idempotency properly in Part VI (it's the key to safe retries), but note the shape now: GET, PUT, DELETE are idempotent — repeating them lands you in the same state — while POST and PATCH generally are not.

Modeling resources in code

Because a resource is really just a well-defined shape plus a set of operations, we can model the types and the routing table in runnable TypeScript. The block below defines the resource type, separate DTOs for create/update (note: no client-supplied id), and a tiny router that maps METHOD path to a handler name — the exact mental model a framework automates for you. It runs through the real TS compiler and prints the resolved routes.

Notice what fell out for free: the create DTO has no id (the server owns identity), the update DTO is all-optional (that is PATCH semantics in the type system), and a POST to an item URL resolves to nothing — which a real framework would turn into a 405 Method Not Allowed. The types encode the design.

Here is what the same design looks like on the wire — show-only, because real HTTP doesn't run in the sandbox:

POST /orders HTTP/1.1
Content-Type: application/json

{ "userId": 42, "total": 99.5 }

HTTP/1.1 201 Created
Location: /orders/1001
Content-Type: application/json

{ "id": 1001, "userId": 42, "total": 99.5, "status": "pending", "createdAt": "2026-07-28T10:04:00Z" }

PATCH /orders/1001 HTTP/1.1
Content-Type: application/json

{ "status": "paid" }

HTTP/1.1 200 OK
Content-Type: application/json

{ "id": 1001, "userId": 42, "total": 99.5, "status": "paid", "createdAt": "2026-07-28T10:04:00Z" }

Representations: collections, single resources, and JSON

A resource and its representation are not the same thing. The order lives in your database as rows; what crosses the wire is a representation of it — today, almost always JSON. The same resource might have multiple representations (JSON, CSV, a summary vs. a full view), negotiated via the Accept header, though most APIs standardize on JSON and move on.

Two shapes recur:

• A single resource (GET /orders/1001) returns one JSON object.
• A collection (GET /orders) returns a list. Wrap it in an envelope so you have room for metadata — total counts, pagination cursors, links — rather than returning a bare top-level array:

GET /orders?status=paid&sort=-createdAt&page=2 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [ { "id": 1002, "status": "paid" }, { "id": 1003, "status": "paid" } ],
  "page": 2,
  "pageSize": 20,
  "total": 57
}

Filtering, sorting, and pagination live in the query string

The path identifies which resources; the query string refines how you want the collection sliced. This is the right home for anything that isn't identity:

• Filter: GET /orders?status=paid&userId=42
• Sort: GET /orders?sort=-createdAt (a leading - for descending is a common convention)
• Paginate: GET /orders?page=2&pageSize=20, or cursor-style ?limit=20&after=eyJpZCI6MTAwMn0

Never return an unbounded collection. A GET /orders on a table with ten million rows must not try to serialize ten million objects — it will exhaust memory and time out. Default to a sane page size and cap the maximum. We design pagination properly in Part VI — cursor vs. offset, stable ordering, the pitfalls of OFFSET on large tables (which ties back to indexing in Databases, Volume 7). For now, the rule is simply: collections are paginated, always.

Statelessness and cacheability

Two REST constraints do a lot of quiet work.

Statelessness means each request carries everything the server needs to handle it — identity, parameters, body — and the server keeps no per-client session memory between requests. The server may (and does) have state in the database; what it doesn't have is a "conversation" with a particular client living in one server's RAM. Why does this matter? Because it makes horizontal scaling trivial: any of your fifty servers can handle any request, since none of them holds context the others lack. A load balancer can spray requests across the fleet freely. (This is exactly why token-based auth beats server-side sessions at scale — Part IV — and it connects to the stateless-services discussion in System Design, Volume 5.)

Cacheability means responses can declare whether and how long they may be reused. Because GET is safe (it doesn't change state) and addresses are stable, a GET /orders/1001 response can be cached — by the browser, a CDN, or a reverse proxy — with headers like Cache-Control and ETag. This is only possible because the design is disciplined: stable URLs, safe reads, honest status codes. An API that returns 200 for errors or mutates state on GET poisons every cache in the path.

HATEOAS and the Richardson Maturity Model

Fielding's REST includes one more constraint that most "REST APIs" quietly skip: HATEOAS — Hypermedia As The Engine Of Application State. The idea is that responses include links telling the client what it can do next, so the client navigates the API by following links rather than hardcoding URLs:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1001,
  "status": "pending",
  "_links": {
    "self":   { "href": "/orders/1001" },
    "pay":    { "href": "/orders/1001/payment", "method": "POST" },
    "cancel": { "href": "/orders/1001", "method": "DELETE" }
  }
}

In theory this makes clients resilient to URL changes and self-documenting. In practice, most APIs skip HATEOAS: JSON clients rarely "discover" links at runtime — they hardcode the endpoints they need — so the extra payload and complexity buy little. It shines in a few niches (some payment and hypermedia-driven APIs), but the pragmatic mainstream stops short of it. Know what it is, be able to define it, and don't feel obligated to build it.

A useful lens for "how RESTful is this?" is the Richardson Maturity Model, which grades an API in levels:

Most well-designed production APIs sit firmly at Level 2, and that is a perfectly respectable place to be. The model is a diagnostic vocabulary, not a ladder you must climb to the top of.

Good vs. bad endpoint design

Put together, the conventions produce a clear sense of "right." Here is the same set of operations designed well and poorly:

The bad column isn't broken — it works — but every row costs the reader a fresh decision, and the inconsistencies compound. The good column is boring, and boring is the highest compliment an API can earn.

Consistency is the real feature

If you take one thing from this chapter, take this: consistency beats cleverness. An API where every collection is plural, every error is a 4xx with the same JSON error shape, every field is camelCase, and every timestamp is ISO-8601 UTC is one a client can learn once and then predict forever. Pick your conventions early and enforce them everywhere:

• Naming: plural nouns, hyphenated paths, no verbs.
• Casing: choose camelCase or snake_case for JSON fields — and never mix.
• Error shape: one envelope for every error, e.g. { "error": { "code": "not_found", "message": "...", "details": [] } }, so clients write one error handler.
• Dates: ISO-8601, UTC, everywhere.
• Pagination: the same params and envelope on every collection.

A written style guide plus a review that rejects deviations is worth more than any framework. The most-loved APIs (Stripe is the standard example) win almost entirely on relentless consistency.

Common Mistakes

• Verbs in the path. POST /createUser, GET /getOrders — the method already carries the verb. Use nouns; let POST/GET/DELETE supply the action.
• 200 OK for errors. Returning success and hiding the failure in the body breaks caching, monitoring, and retries. Failures are 4xx/5xx, always.
• Using GET to change state. GET /orders/1001/cancel looks convenient and is a trap: GET is safe and cacheable, so proxies and prefetchers may fire it and cancel orders you never meant to. State changes use POST/PATCH/PUT/DELETE.
• Unbounded collections. GET /orders returning every row will eventually time out and exhaust memory. Paginate from day one; cap the page size.
• Inconsistent casing and error shapes. user_id here, userId there, three different error formats — each forces the client to special-case. One convention, everywhere.
• Confusing filtering with authorization. ?userId=42 narrows the list; it does not protect it. The server still authorizes the caller.
• Deep nesting. /users/42/orders/1001/items/3/reviews couples URLs to a fragile hierarchy. Once a thing has identity, give it a top-level route.

Summary

• REST is an architectural style, not a protocol: model your domain as resources (nouns) identified by URLs, and act on them with HTTP's fixed set of methods (verbs).
• Name resources as plural nouns (/users, /users/42, /users/42/orders), lower-case and hyphenated, with no verbs in the path — the method carries the action.
• Map CRUD to GET/POST/PUT/PATCH/DELETE with correct status codes: 201 + Location on create, 204 on delete, honest 4xx/5xx on failure — never 200 for an error.
• Collections are paginated and refined via the query string (filter/sort/paginate); the path is identity, the query is refinement. Pagination gets full treatment in Part VI.
• Statelessness buys horizontal scale; cacheability rides on safe GETs and honest status codes — both are why the disciplined design pays off.
• HATEOAS (Level 3) is usually skipped; aim for a clean Level 2 on the Richardson Maturity Model. Above all, consistency — naming, casing, error shapes — is the feature clients feel most.

Next, we turn the request itself under the microscope: validating and parsing input so that "never trust the client" becomes concrete code — because a beautifully designed endpoint that acts on unchecked input is a beautifully designed vulnerability.