REST Maturity Model (Richardson)
You'll learn: How REST APIs evolve from simple RPC-style calls through four maturity levels toward true hypermedia-driven design.
The Core Idea
Leonard Richardson's REST Maturity Model categorizes APIs into four levels (0–3) based on how closely they follow REST principles. Think of it as a ladder of RESTfulness—each rung adds more constraints and capabilities, but not every application needs to climb to the top.
The Four Levels
Level 0: The Swamp of POX (Plain Old XML)
A single URI endpoint, usually POST-only, with all operations encoded in the request body. Example: /api handles everything via different XML/JSON payloads. This is essentially RPC over HTTP—not REST at all.
Level 1: Resources
Introduces multiple URI endpoints representing distinct resources (/users, /orders/123). Still typically POST-heavy, but you're dividing the API into logical pieces. You've discovered resource naming.
Level 2: HTTP Verbs
Proper use of GET, POST, PUT, DELETE with correct semantics. Also leverages HTTP status codes (200, 404, 500). This is where most production APIs land—pragmatic REST. You're now using HTTP as a protocol, not just a transport.
Level 3: Hypermedia Controls (HATEOAS)
Responses include links to related resources and available actions. The client navigates the API by following hyperlinks, like browsing a website. Example: a GET /orders/123 response includes "cancel_link": "/orders/123/cancel". This makes the API self-documenting and discoverable.
Practical Reality
Most teams aim for Level 2 (verbs + status codes). Level 3 adds complexity that benefits generic clients (like web browsers for HTML) but is overkill for tightly-coupled mobile/web apps. However, understanding the model helps you make conscious trade-offs about API design.
Key Takeaway: The Richardson Maturity Model defines four levels of REST adoption—most production systems target Level 2 for balance between RESTfulness and practicality, reserving Level 3 for APIs requiring maximum discoverability.