Reference · REST

Constraints, Maturity & Method Semantics

REST constraintsMaturityStatus codesHTTP methodsREST

Published Jun 21, 2026

The compressed essence. One page to glance at before an interview or a design review. Definitions live in Glossary.

The six architectural constraints

REST is the style you get by applying these to a networked system. Each trades freedom for a system-wide property. Fielding, Ch. 5.

1 · Client–server: Separate UI concerns from data storage. → Each side evolves independently; portability of the UI, scalability of the server.
2 · Stateless: Every request carries all context the server needs; no stored client session between requests. → Any node can serve any request → horizontal scale, visibility, reliability. The most interview-relevant constraint.
3 · Cacheable: Responses must label themselves cacheable or not. → Eliminate round-trips; the basis for ETags, Cache-Control, CDNs.
4 · Uniform interface: One generic contract for all interaction: identified resources, manipulation via representations, self-descriptive messages, HATEOAS. → The central REST distinction; decouples client from server. Costs efficiency (generic > tuned).
5 · Layered system: A client can’t tell if it’s talking to the origin or an intermediary. → Lets you insert gateways, proxies, load balancers, caches transparently.
6 · Code-on-demand (optional): Server may ship executable code to the client (e.g. JS). → The only optional constraint; rarely cited in API interviews.

Richardson Maturity Model

How fully an API uses REST’s ideas. Fowler. Most “REST” APIs in production sit at Level 2 — and a senior can defend that as a deliberate trade-off.

L0The Swamp of POX. One URI, one verb (usually POST); HTTP is a tunnel. Think old-style SOAP/RPC.

L1Resources. Many URIs, each a noun (/orders/42) — but still one verb. Divide and conquer.

L2HTTP verbs. Methods carry meaning (GET/POST/PUT/DELETE) and status codes signal outcome. The pragmatic industry bar.

L3Hypermedia (HATEOAS). Responses carry links advertising valid next actions; clients aren’t hard-coded to URIs. The “Glory of REST” — and the rarest in practice.

HTTP method semantics

Safe = read-only intent. Idempotent = N identical calls ≡ one call’s effect on state. RFC 9110 · MDN.

Method	Safe	Idempotent	Cacheable	Typical use → success code
`GET`	yes	yes	yes	Read a resource → `200`
`HEAD`	yes	yes	yes	Headers only → `200`
`OPTIONS`	yes	yes	no	Capabilities / CORS → `204`
`POST`	no	no	rarely	Create / process → `201` / `202`
`PUT`	no	yes	no	Replace at known URI → `200` / `204`
`PATCH`	no	not reqd	no	Partial update → `200` / `204`
`DELETE`	no	yes	no	Remove → `204` / `200`

Senior gotchas: PATCH is not guaranteed idempotent (depends on the patch document) — make it so when you can. POST isn’t idempotent, which is exactly why retries need an Idempotency-Key (Lesson 3). “Safe” means no intended state change — not “secure” and not “free of all side effects” (a GET may still log).

Status code families

Range	Meaning	Don’t confuse
2xx	Success. `200` ok · `201` created (+`Location`) · `202` accepted (async) · `204` no body	Returning `200` with an error in the body — an anti-pattern.
3xx	Redirect / not-modified. `301`/`308` moved · `304` use your cache	`304` is a feature (conditional GET), not an error.
4xx	Client error. `400` · `401` unauthn · `403` unauthz · `404` · `409` conflict · `422` · `429` rate-limited	`401` = who are you; `403` = you can’t. Different.
5xx	Server error. `500` · `502` · `503` unavailable · `504` timeout	Never use 5xx for a client’s bad input.