Course contentsShow
← Software Engineering
Lesson 797 of 1,93324. REST API DesignFree lesson

HATEOAS Trade-offs and Maturity Models

Richardson Maturity Model, when HATEOAS adds value, and why many APIs stop at level 2.

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.