HATEOAS and the Richardson Maturity Model
On this page
The four levels of the Richardson Maturity Model
Leonard Richardson described four levels of HTTP API design, later popularized by Martin Fowler. Each level uses more of what HTTP offers.
| Level | What it uses | Example |
|---|---|---|
| 0: one endpoint | HTTP as a tunnel for remote procedure calls | POST /api with {"action": "getOrder", "id": 482} |
| 1: resources | Separate URLs per resource, but one verb | POST /orders/482 with {"action": "get"} |
| 2: HTTP verbs | Resources plus proper methods and status codes | GET /orders/482, DELETE /orders/482 → 204 |
| 3: hypermedia | Responses include links to related resources and allowed actions | An order response says how to cancel or pay it |
Most well-designed public APIs sit at level 2: resources, methods, status codes, caching. That's where most practical value is. Level 3 is what Fielding means by REST, and it's rarer.
What is HATEOAS? Links that describe what's possible
HATEOAS (Hypermedia as the Engine of Application State) means the response tells the client what it can do next, like links and buttons on a web page do for a person. An order's available actions depend on its state:
GET /orders/482
{
"id": 482,
"status": "pending",
"_links": {
"self": { "href": "/orders/482" },
"pay": { "href": "/orders/482/payment", "method": "POST" },
"cancel": { "href": "/orders/482/cancellation", "method": "POST" }
}
}After payment, the same request returns:
{
"id": 482,
"status": "paid",
"_links": {
"self": { "href": "/orders/482" },
"receipt": { "href": "/orders/482/receipt" },
"refund": { "href": "/orders/482/refunds", "method": "POST" }
}
}The client shows a "Pay" button only when a pay link is present, instead of duplicating the server's rules about which states allow payment. If the business rules change (say, cancellation is no longer allowed after 24 hours), clients adapt without a release.
Formats like HAL (the _links above), JSON:API, and Siren standardize link structures.
When hypermedia links help, and when they don't
Helps:
- Workflows with state-dependent actions (orders, approvals, bookings): the server decides what's allowed.
- Pagination links (
next,prev), which nearly every API already uses, often in aLinkheader. GitHub's API, for example, answers list requests with a header likeLink: <https://api.github.com/repositories/1/issues?page=2>; rel="next", <...?page=5>; rel="last", so clients follownextinstead of building page URLs themselves. - Long-lived public APIs where URL structures may change: clients follow links instead of building URLs.
Doesn't help much:
- Most client code is written by a developer reading docs, not a generic client discovering the API at runtime. They'll hardcode paths regardless.
- Links add payload size and design effort.
A pragmatic middle ground: be solidly level 2, then add links where they remove duplicated logic: pagination, state-dependent actions, and related resources.
Check yourself
Level 2 uses HTTP methods and status codes with their standard meanings instead of one method with actions in the body.
Clients don't need to duplicate the server's business rules about when an order can be cancelled; they show the action when the link is present. When the rules change, clients follow automatically without a release.
Level 2, resources plus proper HTTP methods and status codes, delivers most of the practical benefits. Full hypermedia adds design and payload cost, and few clients are written to discover actions from links, so the extra effort rarely pays off.
HTTP used only as a transport: every call is a POST to one endpoint with the operation in the body, like many SOAP or JSON-RPC APIs.
For workflows whose allowed actions depend on state, like an order that can be cancelled only before shipping, and for pagination links, where the server controls the next URL.