Richardson Maturity Model: Levels 0 to 3 (HATEOAS)

Developed by Leonard Richardson, the Richardson Maturity Model (RMM) breaks down the principal elements of a RESTful approach into four progressive stages:

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

• Characteristics: Uses HTTP purely as a transport tunneling mechanism for Remote Procedure Calls (XML-RPC, SOAP, or single-endpoint GraphQL/JSON-RPC).
• URI: A single monolithic endpoint, typically POST /api/service.
• Payload: The operation name and arguments are passed entirely inside the request body:

http
Copy
POST /api/service HTTP/1.1
Host: api.example.com
Content-Type: application/json

{ "action": "getUserDetails", "userId": 42 }

Level 1: Distinct Resources

• Characteristics: Introduces individual URIs for distinct business entities, organizing the system into addressable resources instead of a single monolithic endpoint.
• URI: Distinct paths: /v1/users/42, /v1/orders/109.
• Limitation: Often still uses a single HTTP method (like POST) for all operations:

http
Copy
POST /v1/users/42 HTTP/1.1
{ "action": "delete" }

Level 2: HTTP Verbs & Status Codes

• Characteristics: Applies standard HTTP methods according to their formal RFC specifications (GET for safe reads, POST for creation, PUT for full replacement, PATCH for delta updates, DELETE for removal).
• Semantics: Uses accurate HTTP status codes (200 OK, 201 Created, 204 No Content, 404 Not Found, 409 Conflict, 422 Unprocessable).
• Industry Standard: 95% of modern production "REST" APIs operate at Level 2.

Level 3: Hypermedia Controls (HATEOAS)

• Characteristics: Hypermedia As The Engine Of Application State (HATEOAS). Responses include discoverable hypermedia links (_links) that tell the client what operations and state transitions are valid next.
• Advantage: Decouples client routing from hardcoded URL templates. If an order cannot be cancelled because it has already shipped, the server simply omits the cancel link from the response payload.

Hypertext Application Language (HAL) is an IETF draft standard for structuring hypermedia links in JSON:

json
Copy
{
  "order_id": "ord_9082",
  "status": "AWAITING_PAYMENT",
  "amount": 129.50,
  "currency": "USD",
  "items_count": 3,
  "_links": {
    "self": {
      "href": "/v1/orders/ord_9082",
      "method": "GET"
    },
    "payment": {
      "href": "/v1/orders/ord_9082/payments",
      "method": "POST",
      "title": "Submit payment for this order"
    },
    "cancel": {
      "href": "/v1/orders/ord_9082/cancel",
      "method": "POST",
      "title": "Cancel order before payment"
    },
    "customer": {
      "href": "/v1/customers/cus_4102",
      "method": "GET"
    }
  }
}

Dynamic State Transition:

Once the client executes POST /v1/orders/ord_9082/payments and the transaction completes, the subsequent GET /v1/orders/ord_9082 returns:

json
Copy
{
  "order_id": "ord_9082",
  "status": "PROCESSING",
  "_links": {
    "self": { "href": "/v1/orders/ord_9082", "method": "GET" },
    "tracking": { "href": "/v1/orders/ord_9082/tracking", "method": "GET" },
    "refund": { "href": "/v1/orders/ord_9082/refunds", "method": "POST" }
  }
}

Notice that payment and cancel links have disappeared, preventing the client UI from rendering invalid action buttons.

While Roy Fielding famously stated that an API that does not implement HATEOAS is not a true REST API, the industry has predominantly standardized on Level 2.

The Challenges of Level 3 (HATEOAS) in Practice:

1. Payload Bloat: Hypermedia links add 20% to 40% bandwidth overhead to every JSON response, which degrades mobile performance over high-latency cellular networks.
2. Client Complexity & Friction: Frontend web and mobile SDKs prefer static TypeScript types generated from OpenAPI/Swagger contracts over dynamic runtime hypermedia traversal engines.
3. Caching Difficulties: Dynamic link generation often depends on the user's specific authorization role and resource state, reducing edge CDN cache hit ratios.

When Level 3 HATEOAS is Justified:

• Payment & Checkout Gateways (e.g., PayPal): Directing third-party SDKs through multi-step redirect and authorization states.
• Workflow State Engines: Dynamic business process workflows where allowed actions frequently change based on server-side compliance rules.