HATEOAS Trade-offs and Maturity Models
You'll learn: When hypermedia-driven REST makes sense and why most APIs don't use it.
The Richardson Maturity Model
Leonard Richardson created a 4-level scale for REST API maturity:
- Level 0: Single URI, single HTTP verb (basically RPC over HTTP)
- Level 1: Multiple resource URIs, but still limited verbs
- Level 2: Proper HTTP verbs and status codes (where most APIs stop)
- Level 3: Full HATEOAS — hypermedia controls guide clients
Think of it as a ladder: each rung adds more REST principles. Most production APIs climb to Level 2 and stop there.
When HATEOAS Adds Value
HATEOAS shines when:
- Workflow complexity matters: Multi-step processes where available actions change (e.g., order fulfillment: "cancel" available before shipping, "return" after delivery)
- Client-server decoupling is critical: Server can restructure URLs without breaking clients
- Long-lived APIs: Evolvability over years matters more than initial simplicity
- Public APIs with diverse clients: You can't control or coordinate client updates
Why Most APIs Stop at Level 2
The honest truth: HATEOAS adds significant complexity for uncertain benefit:
- Increased response size: Every response carries navigation links
- Client complexity: Clients must parse and follow links instead of hardcoding paths
- Caching complications: Dynamic links can reduce cache effectiveness
- Team familiarity: Most developers know simple REST; HATEOAS requires education
- Diminishing returns: For simple CRUD APIs or internal services, Level 2 is often sufficient
If your API is straightforward, clients are versioned together with the backend, or you prioritize performance over flexibility, Level 2 is a pragmatic stopping point.
Key Takeaway: The Richardson Maturity Model shows REST as a spectrum — Level 2 satisfies most needs, while Level 3 (HATEOAS) trades complexity for long-term evolvability and is best suited for complex workflows or highly decoupled systems.