Richardson Maturity Model Lab (Interactive)

Climb levels 0-3, transition an order through payment, and watch wire format, links, and SDK coupling change. Compare Swamp of POX, resources, HTTP verbs, and HATEOAS side by side: same order, same state machine, four radically different wire contracts.

Richardson Maturity Pyramid

Climb levels 0 to 3, pay the order, and watch wire format, links, and client coupling change.

HTTP request

GET /v1/orders/ord_9082 HTTP/1.1

Response (100 bytes, 200 OK)

{
  "order_id": "ord_9082",
  "status": "AWAITING_PAYMENT",
  "amount": 129.5,
  "currency": "USD"
}

URLs hardcoded in SDK

Link metadata overhead

+0%

Order state

AWAITING_PAYMENT

HTTP semantics used

verbs + codes

Client UI action buttons render from

#Pay order (hardcoded route)

#Cancel order (hardcoded route)

The pragmatic sweet spot (95% of production APIs): verbs and accurate status codes give caching, retries and monitoring for free, but the SDK must hardcode URL templates and guess valid transitions.

How It Works Under the Hood

Leonard Richardson’s maturity model grades how much of REST’s uniform interface an API actually uses. Level 0 tunnels every RPC through one POST endpoint, throwing away caching and status semantics. Level 1 splits entities into discrete URIs but still tunnels verbs. Level 2 applies real HTTP methods and status codes — where 95% of production APIs live. Level 3 adds HAL _links so the server, not hardcoded SDK routes, dictates which state transitions are legal right now, at the price of 20-40% payload overhead.

Core Architectural Principles

Level 0-1 use HTTP as a transport tunnel, blinding CDNs, load balancers, and monitors to request intent.
Level 2 maps CRUD onto GET/POST/PUT/PATCH/DELETE with accurate 2xx/4xx codes.
Level 3 HATEOAS omits invalid action links after a transition, preventing client-side illegal moves.

Interview Round Script

Name all four levels precisely, then show pragmatism: target Level 2 plus OpenAPI for 99% of services because generated typed clients beat runtime hypermedia traversal on mobile, but justify Level 3 for PayPal-style checkout flows where the server must steer third-party SDKs through dynamic authorization states.

Key Trade-Offs

Level 3 decouples clients from URI schemes and enforces server-driven state machines, but taxes every response with link metadata.

Related Curriculum Chapter