Course contentsShow
← System Design
Lesson 1881 of 1,91945. API Design and VersioningFree lesson

HATEOAS: Hypermedia as the Engine of Application State

Including links in responses so clients can discover actions dynamically, though rarely fully adopted.

HATEOAS: Hypermedia as the Engine of Application State

What You'll Learn

You'll understand how HATEOAS enables self-describing APIs by embedding action links directly in responses, though its real-world adoption remains limited.

The Core Idea

HATEOAS (Hypermedia as the Engine of Application State) is a REST constraint that turns API responses into interactive roadmaps. Instead of clients needing hardcoded knowledge of available endpoints, the server includes hyperlinks in each response that tell the client what actions are possible next—similar to how web browsers navigate pages by following links, not memorizing URLs.

Think of it like a choose-your-own-adventure book: each page (response) tells you which page numbers (endpoints) you can jump to based on the current story state, rather than requiring you to know the book's entire structure upfront.

How It Works

When you GET a resource, the response includes not just data but also _links or similar hypermedia controls:

{
  "orderId": "123",
  "status": "pending",
  "_links": {
    "self": {"href": "/orders/123"},
    "cancel": {"href": "/orders/123/cancel", "method": "DELETE"},
    "pay": {"href": "/orders/123/payment", "method": "POST"}
  }
}

If the order status changes to "shipped", those action links disappear—the server dynamically communicates what's allowed. Clients discover capabilities instead of assuming them.

Why It's Rarely Adopted

While elegant in theory, HATEOAS faces practical challenges:

  • Increased payload size with repetitive links
  • Client complexity parsing and following links
  • Most teams prefer explicit API documentation over dynamic discovery
  • Mobile/web apps often need predictable, cached endpoints
  • Tooling and frameworks provide weak support

Key Takeaway:
HATEOAS makes APIs self-documenting by embedding navigational links in responses, enabling true REST decoupling, but its complexity and limited real-world benefit mean most production systems skip it in favor of simpler, documented endpoints.