Richardson

The Richardson Maturity Model (RMM) is a model developed by Leonard Richardson to evaluate how well a web API follows REST principles. It defines four levels (0 to 3), each building on the previous one, showing the maturity of an API in terms of its RESTful characteristics.

Level	Description	Key Features
0	The Swamp of POX	Single URI, uses HTTP as a transport tunnel (often only POST)
1	Resources	Exposes multiple URIs (endpoints) for resources
2	HTTP Verbs	Uses standard HTTP methods like GET, POST, PUT, DELETE
3	Hypermedia Controls (HATEOAS)	Uses hyperlinks in responses to guide client interaction

Level 0: The Swamp of POX (Plain Old XML)

Description:

• Single URI (/api)
• Only uses POST for every action
• Request tells the server what to do using action names (RPC-style)
• Often uses XML or JSON, but not in a RESTful way

Example:

POST /api
{
  "action": "getBook",
  "bookId": 123
}

Problems:

• No use of HTTP verbs
• No resource-based URIs
• Violates REST constraints

Level 1: Resources

Description:

• Exposes multiple URIs to represent resources (e.g., /books, /authors)
• Still may use only POST

Example:

POST /books/get
{
  "id": 123
}

Improvements:

• Introduces the concept of resources
• Each resource has its own URI

Still Lacking:

• Proper use of HTTP verbs (e.g., still using POST for everything)

Level 2: HTTP Verbs

Description:

Uses HTTP methods properly:

• GET for retrieving
• POST for creating
• PUT for updating
• DELETE for deleting

Also uses standard HTTP status codes (200, 201, 404, etc.)

Example:

GET /books/123           → Get a book
POST /books              → Create a book
PUT /books/123           → Update a book
DELETE /books/123        → Delete a book

Improvements:

• Fully leverages the capabilities of HTTP
• Improves clarity, scalability, and cacheability

Still Lacking:

• No discovery or navigation via hyperlinks

Level 3: Hypermedia Controls (HATEOAS)

HATEOAS = Hypermedia As The Engine Of Application State

Description:

• The API provides hyperlinks in responses
• Clients can discover available actions by following links
• Fully REST-compliant
• Promotes decoupling and flexibility

Example:

GET /books/123

Response:
{
  "id": 123,
  "title": "RESTful Web Services",
  "author": "Leonard Richardson",
  "_links": {
    "self": { "href": "/books/123" },
    "update": { "href": "/books/123", "method": "PUT" },
    "delete": { "href": "/books/123", "method": "DELETE" },
    "author": { "href": "/authors/7" }
  }
}

Benefits:

• Client doesn’t need to hardcode URIs or workflows
• Server guides the client like a human browsing a website
• Ideal for long-term evolution and discoverability

Summary of Richardson Maturity Levels

Level	URI Structure	HTTP Verbs	Hypermedia (HATEOAS)	RESTful?
0	No	No	No	❌
1	✅	No	No	❌
2	✅	✅	No	✅ (Partial)
3	✅	✅	✅	✅ (Full)

• Most real-world REST APIs are at Level 2 — they use URIs and HTTP verbs correctly but often skip HATEOAS.
• Level 3 is ideal for discoverability and hypermedia-driven clients, but it requires more complexity and isn't always necessary.