skip to content

Walk through the four levels of the Richardson Maturity Model for HTTP APIs, from level 0 to level 3, with an example of what an API looks like at each level.

level: middleimportance: should knowfreq 45%

answer

  1. 0 = one URL one verb, POX swamp
  2. 1 = many resource URLs
  3. 2 = verbs + status codes (industry norm)
  4. 3 = hypermedia links, discover next action
  5. descriptive ladder, not a scorecard

basics

~20 s

Level 0: one URL, one verb, the operation named in the body. Level 1: many resource URLs. Level 2: proper HTTP verbs and status codes per resource. Level 3: responses carry hypermedia links telling the client what it can do next.

solid answer

~50 s

The model grades how much of HTTP an API actually uses. - **Level 0 (the "POX swamp")**: a single endpoint, typically `POST /api`, with the operation named inside the body. HTTP is a tunnel; SOAP and most JSON-RPC sit here. - **Level 1 (resources)**: the API splits into many addressable URLs (`/orders/42`, `/customers/7`), but often still POSTs everything and returns 200 with an error flag in the body. - **Level 2 (verbs and status codes)**: GET reads, POST creates, PUT/PATCH update, DELETE removes, and responses use real status codes (201, 404, 409, 422). GETs become cacheable and safely retryable. Nearly every API called "REST" in industry lives here. - **Level 3 (hypermedia controls)**: representations embed links with relation names, so a client discovers `cancel` or `next` from the response rather than hardcoding URL templates. It is a description of maturity, not a scorecard: level 2 is a legitimate place to stop.

code

http · 18 lines
http
POST /api HTTP/1.1
Content-Type: application/json

{"op":"cancelOrder","orderId":42}

HTTP/1.1 200 OK
{"status":"error","message":"already shipped"}

---

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

{}

HTTP/1.1 409 Conflict
Content-Type: application/problem+json
{"title":"Order already shipped"}

go deeper

for a junior

Recall the four rungs in order and give one concrete example each; naming level 2 as the everyday norm is enough.

for a middle

Explain what each rung buys you mechanically - addressability at 1, caching and retries at 2 - and give a correct status-code example.

for a senior

Connect the rungs to operational payoffs: cache and proxy behaviour, gateway policy, retry safety, and why teams stop at 2.

for a principal

Frame it as a descriptive vocabulary for contract decisions and steer the conversation to client coupling and evolution cost rather than compliance.

## What the model is The Richardson Maturity Model (RMM) is a four-rung ladder describing how much of HTTP an API leans on. It exists so teams can say *which rungs an API has climbed* instead of arguing whether it "is REST". Each rung assumes the ones below it. ## Level 0 - the plain-old-XML (POX) swamp One URL, one method. Everything goes to something like `POST /api` and the body says what to do: `{"op":"getOrder","id":42}`. HTTP is used purely as a transport tunnel; the fact that it has methods, URLs and status codes is ignored. Classic SOAP services and most JSON-RPC endpoints are level 0. Consequences: nothing is cacheable by intermediaries, every response is 200 even for failures, and no generic tooling (proxy, CDN, log analyser) can tell one operation from another. ## Level 1 - resources The API introduces many URLs, one per *thing*: `/orders`, `/orders/42`, `/customers/7/addresses`. Nouns replace a single RPC door. But the verb is often still POST for everything, and errors still come back as `200 OK` with `{"status":"error"}`. The win is real but modest: identity and addressability. Logs, metrics and authorisation rules can now be scoped per resource. ## Level 2 - HTTP verbs and status codes The API uses the method set as it is defined: GET to read (safe, cacheable), POST to create or run a non-idempotent action, PUT to replace, PATCH to modify partially, DELETE to remove. Responses use the status code space meaningfully: 201 with a `Location` header for a create, 204 for a delete, 404 for a missing resource, 409 for a conflict, 422 for a semantically invalid body. This is where the protocol starts paying rent: caches can store GETs, proxies and clients can retry idempotent methods, monitoring can alert on 5xx without parsing bodies, and API gateways can apply policy by method. In practice "a REST API" in industry means level 2. ## Level 3 - hypermedia controls Responses do not just carry data, they carry the *affordances*: links naming what can be done next, with a machine-readable relation name. An order representation might include a `cancel` link only while cancelling is legal, and a `next` link only if another page exists. The client follows relation names it understands rather than composing URLs from string templates in its own code. Formats such as HAL and JSON:API standardise where those links go. The payoff is decoupling: URL structure becomes the server's business, and workflow state is communicated rather than duplicated in client logic. The costs are real - bigger payloads, more sophisticated clients, no widely adopted generic hypermedia client, and documentation that is harder to write. ## How to talk about it Name the levels, then say plainly that level 2 is the industry norm and the model is descriptive, not an obligation to reach 3.

  • Is an API at level 2 allowed to be called RESTful?
    Colloquially yes, and that is how the industry uses the word. Strictly, Fielding's dissertation treats hypermedia as a required constraint, so a level-2 API is HTTP-shaped rather than fully REST. The useful move in an interview is to acknowledge both readings and then discuss tradeoffs rather than police vocabulary.
  • Which rung gives you the biggest practical return?
    Level 2. Correct verbs and status codes unlock caching, safe retries, gateway policy and body-free monitoring - all from generic infrastructure you did not write. Level 1 only buys addressability, and level 3's benefits require client sophistication that most consumers never build.

Level 0 is a single reception desk where you shout what you want; level 1 gives every department its own door; level 2 means the doors respect 'push', 'pull' and 'staff only' signs; level 3 pins a map on each door showing where you can go next.

saying these in an interview costs you the question

  • Claiming level 3 is mandatory for an API to be useful
  • Describing level 1 as 'using proper verbs' - that is level 2
  • Thinking the levels are about payload format (XML vs JSON) rather than protocol use
  • Saying level 2 means 'returns JSON'
  • Treating the model as an official specification rather than a descriptive heuristic

context

resolving links…