What is HATEOAS and the Richardson Maturity Model?

Question

IT Interview Practice · Accepted Answer

The **Richardson Maturity Model (RMM)** grades how "RESTful" an API is across four levels, and **HATEOAS** is the top level — the constraint most people skip.

## The four levels

```text
Level 0 — "The Swamp of POX": one URI, one method (RPC over HTTP).
          POST /api  { "action": "getUser", "id": 42 }
Level 1 — Resources: many URIs, but still one verb.
          POST /users/42  ,  POST /users/42/delete
Level 2 — HTTP Verbs: proper methods + status codes (where most "REST" APIs live).
          GET /users/42 → 200 ,  DELETE /users/42 → 204
Level 3 — Hypermedia Controls (HATEOAS): responses link to what you can do next.
```

Most production "REST" APIs are **Level 2** — correct resources, methods, and status codes. That's usually good enough, and it's a perfectly reasonable target.

## HATEOAS (Level 3)

**HATEOAS** = *Hypermedia As The Engine Of Application State*. The idea: a response includes **links** telling the client what actions are available next, so the client navigates the API by following links rather than hardcoding URLs — like a human following links on a web page instead of memorizing every URL.

```http
GET /orders/1001 HTTP/1.1
```
```http
HTTP/1.1 200 OK
Content-Type: application/json

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

Because the order is `pending`, the server offers `pay` and `cancel` links. Once paid, those links disappear and a `refund` link might appear — **the server drives state transitions**, and the client just follows whatever links it's given.

## Why it's rare

The promise is decoupling: clients don't hardcode URLs, so the server can restructure them freely. In practice most clients hardcode anyway, HATEOAS adds real complexity, and formats never fully standardized (HAL, JSON:API, Siren all compete). The payoff rarely justifies the cost.

## Why it matters

This is a classic senior-level question because it separates people who **understand REST as originally defined** from those who use "REST" loosely to mean "JSON over HTTP." The valuable insight isn't reciting the four levels — it's the judgment to say that **Level 2 is the pragmatic sweet spot** while knowing that true REST (Fielding's definition) *requires* HATEOAS, and being able to explain *why the industry mostly ignores it*: the decoupling benefit is real but rarely realized because clients hardcode URLs regardless, and the added complexity plus competing hypermedia formats don't pay off for typical APIs. Demonstrating you know what HATEOAS *is*, can show a concrete state-driven-links example, and can argue honestly about the cost/benefit — rather than dogmatically insisting every API must be Level 3 — is exactly the balanced, experience-based judgment interviewers are probing for.

The four levels

HATEOAS (Level 3)

Why it's rare

Why it matters

Related questions