REST principles

REST is an architectural style, not a protocol or a spec: the constraints Roy Fielding set out in chapter 5 of his 2000 dissertation to explain why the web scales. Each constraint induces a property, and together they buy one thing worth remembering: a component that knows nothing about your application - a CDN, a proxy, a gateway, a client library - can still act correctly on your messages.

“RESTful” in industry means less: resources, HTTP methods and status codes, usually without hypermedia. That is a defensible place to stop. Not knowing which constraints you kept, and what the dropped ones would have bought, is not.

The six constraints

Fielding adds them one at a time, in this order, and names what each buys and what it costs. The costs are what separates a senior answer from a list.

Client-server

Separate the user interface from data storage.

• Buys: both sides evolve independently, so one API serves web, mobile and partners on their own release cycles.
• Violated: an API that returns layout - which widgets, in what order - has taken on the UI’s concerns, so every redesign becomes an API release. A client that needs its own shape gets a backend-for-frontend its team owns.

Stateless

“Each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server. Session state is therefore kept entirely on the client.”

• Buys: visibility (one request can be understood alone), reliability (partial failures are easier to recover from) and scalability (no per-client memory, so any node serves any request).
• Costs: every request repeats its context: token, ids, filters.
• Violated: POST /select-account then GET /transactions works until a retry or a deploy lands the second call on a node that never saw the first.

It concerns session state - what this client did before - not the database, which is full of state and fine. Depth, and why revocation forces a lookup anyway: Stateful and stateless.

Cacheable

Every response is labelled, implicitly or explicitly, as cacheable or not.

• Buys: some interactions disappear entirely: lower latency, less load.
• Costs: a cache can serve data staler than the origin’s.
• Violated: an unlabelled response can still be cached by heuristic - typically for 10% of its age since Last-Modified (RFC 9111). Per-user data needs private: by default a shared cache refuses to reuse a response only when the request carried Authorization - a cookie does not count - and public or s-maxage lifts even that. A body that varies by Accept-Language or Accept-Encoding needs Vary naming the header, or one client’s variant is served to another.

Uniform interface

One generic interface between all components; Fielding calls it “the central feature that distinguishes the REST architectural style”. It has four parts:

1. Identification of resources. Anything nameable is a resource with a URI, and a resource is a concept, not a row - Fielding’s example is “today’s weather in Los Angeles”. /users/42, /me and /search?q=kettle all count.
2. Manipulation through representations. Clients GET a representation, change it and send it back; the server decides what that means for state. JSON is convention, not a rule: Accept asks, Content-Type labels.
3. Self-descriptive messages. Method, URI, media type, cache directives and status code carry everything needed to process a message - no out-of-band rules like “on this endpoint a 200 can be a failure”.
4. Hypermedia as the engine of application state (HATEOAS). Responses link to the next valid transitions, so clients follow links rather than build URLs. The least implemented part - see Richardson Maturity Model and HATEOAS.

• Buys: generic components. A cache or client library works with every API without knowing any of them, and implementations evolve behind it.
• Costs: efficiency. Data moves “in a standardized form rather than one which is specific to an application’s needs” - the gap GraphQL and gRPC fill.
• Violated: everything tunnelled through POST /api with the action in the body, which blinds every intermediary (next section).

The methods belong to the interface: GET is safe, PUT and DELETE idempotent, POST neither, and PATCH idempotent only if its body makes it so. The grid is in HTTP semantics and caching, PUT versus PATCH in PUT vs PATCH: which writes are safe to retry.

Layered system

Each component sees only the layer it talks to; a client cannot tell the origin from a CDN, a gateway or a load balancer.

• Buys: intermediaries insertable at will: caches, load balancers, WAFs, adapters in front of legacy systems.
• Costs: latency per hop, which shared caching can repay.
• Violated: state bound to a TCP connection. NTLM authenticates the connection, not the request, so every proxy must pin a client to one upstream connection - nginx’s commercial ntlm directive exists for that.

Code on demand (optional)

Servers may extend clients by sending code: applets in 2000, JavaScript now. It buys simpler clients and costs visibility - no intermediary can know what the code will do - which is why it is the one optional constraint.

The mechanism: intermediaries that know nothing about you

Fielding’s summary: “REST enables intermediate processing by constraining messages to be self-descriptive: interaction is stateless between requests, standard methods and media types are used to indicate semantics and exchange information, and responses explicitly indicate cacheability.” Three intermediaries, each deciding from the message alone, never from your JSON:

CDN      GET /products/42, answered max-age=60
         -> served from the edge for 60 s, keyed by URL
nginx    PUT /carts/7, upstream connection reset
         -> retried on the next upstream: idempotent
         POST /orders, same failure
         -> 502, not retried: not idempotent
gateway  DELETE /users/42 with a read-only API key
         -> 403 before your code runs

nginx has behaved like that since 1.9.13: proxy_next_upstream never passes a POST, LOCK or PATCH to another server once sent, unless you add non_idempotent. urllib3’s Retry agrees; its default allowed_methods are DELETE, GET, HEAD, OPTIONS, PUT and TRACE.

Caches go further. RFC 9111 makes a cache invalidate a URI when an unsafe method on it succeeds, so PUT /products/42 evicts the cached GET /products/42 - because the write and the read name the same resource. Only caches on the PUT’s path hear about it; every other copy lives until it goes stale.

Rewrite it all as POST /api {"action": ...} and nothing is cacheable, retryable or invalidated, and the gateway must parse your body to authorize.

The cache constraint in practice is Cache-Control plus an ETag: a CDN answers from its copy while it is fresh, then revalidates with If-None-Match and pays for a body only when the resource changed. The mechanics - validators, 304, what may be stored - are in HTTP semantics and caching.

Resource modelling and URL design

Resources are nouns; the methods are the verbs.

• Plural collections, items by id: /orders, /orders/42. Ids are opaque and stable - never an email or a name that can change.
• Model what clients need, not your tables: a join (/users/42/feed), a computed view (/orders/42/receipt), a process (/jobs/7f3a).
• Filters, sorting and paging go in the query string (REST Versioning and Pagination); a new path segment means a new resource.
• Nest one level, for ownership. Once a child has its own identity, give it a top-level URI.

Actions that are not CRUD

Cancel, capture, merge. Four conventions, all in production use:

The first is the most RESTful: the cancellation is a thing with its own id, reason, author and time, and GET /orders/42/cancellation answers “who cancelled this, and why” without an audit-log dig. The other three are RPC-shaped and honest about it; AIP-136 itself says to prefer standard methods where they fit.

GitHub’s PUT is the instructive one: merging twice leaves the same state as merging once, so the method alone tells any retry policy that a resend is harmless. The first row can borrow that: an order has at most one cancellation, so PUT /orders/42/cancellation is idempotent too.

Avoid PATCH /orders/42 {"status": "cancelled"} when cancelling refunds money or sends email: a field write that secretly runs a workflow hides the transition from logs, permissions and reviewers.

Status codes the interface leans on

400 versus 422, 401 versus 403 and the Retry-After codes are in Status codes. One error body everywhere: application/problem+json, RFC 9457, which obsoleted RFC 7807 in 2023.

GET must be safe

RFC 9110 defines safe as “the client does not request, and does not expect, any state change on the origin server”, so spiders and prefetchers can work “without fear of causing harm”; a URI that selects an action, like page?do=delete, MUST refuse it on a safe method. Who sends the GETs nobody clicked:

• Prefetchers. In May 2005 Google Web Accelerator prefetched every link on a page, “delete” links included and JavaScript confirmations skipped, and 37signals’ Backpack users watched their pages disappear. Today a site’s Speculation Rules make Chrome prefetch links on hover or sooner, sent with Sec-Purpose: prefetch.
• Mail scanners. Microsoft Defender Safe Links and similar scanners fetch links in mail to check them, so one-time sign-in links arrive already used. RFC 8058 exists because anti-spam software fetched unsubscribe URLs “without any action by the user”.
• Unfurlers. Slack (Slackbot-LinkExpanding), Teams and most messengers fetch a pasted URL to build its preview.
• Link checkers, often with HEAD - which Flask, Django’s views and Starlette’s Route answer by running your GET handler, side effects included.

The fix: the GET shows, the POST acts

GET /unsubscribe?token=8f3c HTTP/1.1

HTTP/1.1 200 OK
Content-Type: text/html

<form method="post"><button>Unsubscribe</button></form>

A person clicks and the browser POSTs to the same URL; a scanner stops at the page. Magic sign-in links work the same way, and RFC 8058 makes mail’s one-click unsubscribe a POST (List-Unsubscribe-Post: List-Unsubscribe=One-Click), which Gmail and Yahoo have required of bulk senders since 2024. To catch stragglers, log method, user agent and Sec-Purpose on state-changing routes.

Long-running work: 202, a status resource, 303

A ten-minute report cannot be one request. An AWS ALB and nginx give up on a silent upstream after 60 s by default, Cloudflare after 125 s (its documented default, as of 2026-10). The client gets a 504 (or 524) while the first build may still be running, retries the POST, and the report is built twice. Make the job a resource:

1. POST /reports validates, enqueues and answers 202 Accepted with Location pointing at a status resource and a Retry-After hint. Both are convention on a 202: RFC 9110 defines Location for 201 and 3xx, and gives Retry-After specific meaning only on 503 and 3xx.
2. GET /jobs/{id} answers 200 with the job’s state while it runs - the “status monitor” RFC 9110 says a 202 ought to point to.
3. When done it answers 303 See Other to the result: a separate resource, bookmarkable, and cacheable because it never changes.
4. On failure it answers 200 with "status": "failed" and an RFC 9457 problem object. Azure’s async request-reply pattern answers that poll with a matching 4xx instead; pick one and document it.

On the wire

POST /reports {"month": "2026-09"}
  -> 202 Accepted, Location: /jobs/efc002c4, Retry-After: 5

GET /jobs/efc002c4
  -> 200 {"status": "running"}, Retry-After: 5

GET /jobs/efc002c4               (later)
  -> 303 See Other, Location: /reports/efc002c4

What production adds

• BackgroundTasks runs inside the web process, so a deploy kills the job; enqueue to a durable queue instead - see Async I/O and background work.
• An Idempotency-Key on the POST makes a retried submit return the existing job (Idempotency).
• DELETE /jobs/{id} cancels; a completion webhook spares the client the polling (Webhooks).
• httpx does not follow redirects unless told to (follow_redirects=True); requests and browsers do, so document what the status URL returns.

Batches and partial failure

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

{"items": [{"sku": "KETTLE-1", "qty": 2}, {"sku": "NOPE", "qty": 1}]}

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

{"results": [
  {"index": 0, "status": 201, "location": "/orders/881"},
  {"index": 1, "status": 422, "error": {"title": "Unknown SKU"}}
]}

• Say atomic or best-effort in the contract. Atomic is one transaction and one honest status. Best-effort returns per-item results, and the client retries only the failures, so each item needs its own idempotency key.
• The top-level code only says the batch parsed. 207 Multi-Status is WebDAV’s (RFC 4918), with an XML body by default; Microsoft Graph’s $batch answers 200 with a status per item.
• A batch gives up caching, a status that monitoring and gateways can read (a 200 can hide twenty failures, so emit per-item metrics), and per-resource authorization and rate limits.

Chattiness, in round trips

An order screen needs the order, its 20 line items and each item’s product, modelled as separate resources. At a 100 ms round trip, warm connections, server time ignored:

Browsers open about six HTTP/1.1 connections per origin, so 20 requests leave in four waves. HTTP/2 multiplexes them on one connection (HTTP versions: 1.1, 2 and 3) but cannot break the dependency chain: products cannot be requested before the items naming them arrive.

A compound document (include is JSON:API’s syntax), embedding the items, or a BFF collapses the chain to one round trip. When every screen wants a different shape, that is GraphQL’s case; when the chatter is between services, gRPC’s.

Where REST stops

Richardson maturity, as a pointer

Level 0 is one endpoint with the action in the body, level 1 adds resources, level 2 adds HTTP methods and status codes, level 3 adds hypermedia. Leonard Richardson presented it at QCon in 2008, and Martin Fowler’s 2010 article popularised it.

Industry “REST” is level 2. Fielding’s 2008 post “REST APIs must be hypertext-driven” says an API not driven by hypertext is not REST - level 3 or nothing. Level 2 plus an OpenAPI contract is the usual stopping point, and the case for it is in Richardson Maturity Model and HATEOAS.

RPC over HTTP, labelled or not

Slack’s Web API calls itself “HTTP RPC-style”: POST /api/chat.postMessage, and a failure is HTTP 200 with {"ok": false, "error": "channel_not_found"}. That is a legitimate, labelled design. The trouble is RPC that calls itself REST, and the fix is the same work done through the uniform interface:

before  POST /api/v1/getOrderStatus  {"orderId": 42}
        -> 200 {"success": false, "error": "NOT_FOUND"}
after   GET /api/v1/orders/42
        -> 404, Content-Type: application/problem+json

The first is a read no cache can store, a request no client may retry on its own, and a failure every dashboard counts as success.

REST vs RPC vs GraphQL vs gRPC

The middle column is the argument: REST’s constraints exist so that column says something an intermediary can act on, and the other three trade it for action-shaped calls, client-chosen shapes or binary speed. GraphQL may use GET for queries (never mutations, per the GraphQL-over-HTTP draft), so a CDN can cache them; gRPC needs gRPC-Web or a proxy to reach a browser. More in API Protocols Comparison — REST, GraphQL, gRPC, SOAP.