Richardson Maturity Model

Best Practice: Richardson Maturity Model

The Richardson Maturity Model (RMM) grades an HTTP API by how completely it uses the building blocks of REST. Leonard Richardson introduced it in 2008, and Martin Fowler popularized it. It defines four levels: Level 0 is a single endpoint tunneling RPC over HTTP (often POST-only); Level 1 introduces resources with distinct URIs; Level 2 uses HTTP verbs and status codes correctly (GET, POST, PUT, DELETE, 200, 404, 201); and Level 3 adds hypermedia controls (HATEOAS) so responses link to related actions. The model matters because it gives teams a shared, objective vocabulary to assess and plan API design instead of arguing about whether something is "truly REST."

Step-by-Step Implementation Guidance

1. Audit your current API and place each endpoint on a level. Most legacy APIs sit at Level 0 or 1.
2. Move to Level 1 by modeling distinct resources, each with its own URI (for example /orders/123 instead of one /api endpoint).
3. Move to Level 2 by mapping operations to HTTP methods and returning correct status codes. Make GET safe and idempotent; use 201 for creation and 4xx/5xx meaningfully.
4. Adopt consistent media types (application/json) and content negotiation via Accept headers.
5. Move to Level 3 by embedding hypermedia links in responses so clients discover next actions instead of hardcoding URLs.
6. Pick a target level deliberately. Level 2 is the pragmatic norm; pursue Level 3 only when client decoupling justifies the cost.

Common Mistakes Teams Make When Ignoring This Practice

• Tunneling everything through POST and calling it REST (stuck at Level 0).
• Using GET for state-changing operations, breaking caching and idempotency expectations.
• Returning HTTP 200 with an error payload instead of proper 4xx/5xx codes.
• Treating HATEOAS as mandatory and over-engineering simple internal APIs.
• Designing verb-based URIs like /getUser instead of resource nouns.

Tools and Techniques That Support This Practice

• OpenAPI (Swagger) to document resources, verbs, and status codes.
• Postman and curl for verifying verb and status-code behavior.
• HAL, JSON:API, and Siren as hypermedia formats for Level 3.
• Linters such as Spectral to enforce RESTful conventions in CI.

How This Practice Applies to Different Migration Types

• Cloud Migration: Re-platforming services is a chance to lift APIs from Level 0/1 to Level 2 behind a gateway.
• Database Migration: Resource modeling at Level 1 clarifies which entities map to which tables and endpoints.
• SaaS Migration: Integrating with a SaaS API often means consuming a Level 2 or 3 design; understanding the model speeds onboarding.
• Codebase Migration: When rewriting a monolith into services, use RMM as a checklist so new endpoints land at a consistent maturity level.

Checklist

• Each endpoint placed on an RMM level.
• Resources have distinct, noun-based URIs (Level 1).
• HTTP verbs and status codes used correctly (Level 2).
• Content negotiation via media types in place.
• Hypermedia links added where decoupling is needed (Level 3).
• Target maturity level agreed and documented.
• CI linting enforces conventions.