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

HATEOAS Fundamentals

Hypermedia As The Engine Of Application State: embedding links in responses to guide client navigation.

HATEOAS Fundamentals

What you'll learn: How embedding navigation links in API responses allows clients to discover available actions dynamically, just like clicking links on a webpage.

The Core Idea

HATEOAS (Hypermedia As The Engine Of Application State) means your REST API responses include hyperlinks that tell the client what they can do next. Instead of hardcoding all possible API endpoints into the client, the server guides navigation by providing relevant links within each response.

Think of it like browsing a website: you don't memorize every URL—you click links the page provides. HATEOAS brings this same principle to REST APIs.

How It Works

When a client requests a resource, the server responds with both the data and links to related actions or resources. These links show the client its options based on the current state.

For example, when fetching an order, instead of just returning order details, include links like:

{
  "orderId": 123,
  "status": "pending",
  "total": 49.99,
  "_links": {
    "self": { "href": "/orders/123" },
    "cancel": { "href": "/orders/123/cancel" },
    "pay": { "href": "/orders/123/payment" }
  }
}

If the order were already paid, the pay link wouldn't appear—the server controls which actions are available.

Why It Matters

HATEOAS decouples clients from hardcoded API knowledge. Clients don't need to construct URLs or remember every endpoint. They follow links the server provides, making APIs more flexible and evolvable. When you add new features or change URLs, properly designed hypermedia guides clients automatically.

Key Takeaway: HATEOAS embeds navigation links in API responses, allowing the server to guide clients through available actions based on current resource state, reducing client-side coupling and enabling dynamic discoverability.