Course contentsShow
← System Design
Lesson 1886 of 1,91945. API Design and VersioningFree lesson

REST Maturity Model (Richardson)

Levels 0-3 from RPC-style APIs to fully hypermedia-driven, understanding practical adoption levels.

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.