The Richardson Maturity Model and Hypermedia

Four levels describe how much of the web an API uses, from one endpoint to responses that link to what comes next.

The Richardson maturity model, described by Leonard Richardson and popularised by Martin Fowler, ranks an API by how much of HTTP it uses, in four levels. Level 0 sends every call to one URL; level 1 gives each resource its own URL; level 2 uses HTTP methods and status codes for their meaning; level 3 adds hypermedia, links in each response to what the client may do next. Most well-designed APIs sit at level 2.

The four levels, what each adds, and how one request looks at each
Level	Adds	Cancelling order 42
0, one endpoint	HTTP as a pipe for remote calls	POST /api {"action": "cancelOrder", "id": 42}
1, resources	A URL per resource	POST /orders/42 {"action": "cancel"}
2, methods and codes	Methods and status codes used for their meaning	POST /orders/42/cancellation, answered 201
3, hypermedia	Responses link to the next possible actions	As level 2, and the order's response carries a link to cancel it

What each level buys. Level 1 lets logs, permissions and documentation be organised by resource. Level 2 lets the software in between act correctly: caches store GETs, clients retry PUTs, monitoring counts 5xx responses. That is why it is where the practical value is.

What level 3 looks like. An order's response carries links for what is possible now:

json

{"id": 42, "status": "paid",
 "links": {"self": "/orders/42",
           "cancel": "/orders/42/cancellation",
           "items": "/orders/42/items"}}

When the order ships, the cancel link disappears, so the client learns what is allowed from the response instead of copying the rule from the documentation. Formats such as HAL and JSON:API standardise where such links go.

Why most APIs stop at level 2. Hypermedia pays off when clients are written to follow links, as browsers follow them on web pages. Most API clients are written against documentation and hard-code paths, so the links go unread. Pagination is the common exception: a next link is used everywhere.

So aim for level 2 by default, and add links where clients will actually follow them.

← → move through sections and cards