What is HATEOAS in REST: Simple Explanation and Example

HATEOAS stands for Hypermedia As The Engine Of Application State and is a constraint of REST APIs that lets clients navigate the API dynamically by following links provided in responses. It means the server tells the client what actions are possible next, making the API self-descriptive and easier to use without prior knowledge of all endpoints.

How It Works

Imagine you are exploring a city with a map that shows not only your current location but also the nearby places you can visit next. HATEOAS works like that map for a REST API. Instead of hardcoding URLs or guessing what to do next, the client receives links in the response that tell it where to go or what actions to take next.

This means the server controls the flow of the application by providing URLs and instructions dynamically. The client just follows these links, like clicking buttons on a website, to move through the API. This makes the API easier to evolve and reduces errors because clients don’t need to know all URLs upfront.

Example

This example shows a simple REST API response for a user resource that includes HATEOAS links to related actions.

json

{
  "id": 1,
  "name": "Alice",
  "links": [
    { "rel": "self", "href": "/users/1" },
    { "rel": "friends", "href": "/users/1/friends" },
    { "rel": "update", "href": "/users/1" }
  ]
}

When to Use

Use HATEOAS when you want your REST API to be more flexible and self-explanatory. It is especially helpful in large or complex APIs where clients benefit from guidance on what actions are possible next.

For example, in an online store API, after fetching a product, the response can include links to add the product to the cart, view reviews, or check related products. This helps clients navigate the API without hardcoding URLs or guessing available operations.

Key Points

• HATEOAS makes REST APIs self-descriptive by including links in responses.
• Clients discover available actions dynamically by following these links.
• It improves API flexibility and reduces client-server coupling.
• Commonly used in hypermedia-driven REST APIs.

Key Takeaways

HATEOAS lets REST API clients navigate by following links provided in responses.

It makes APIs self-descriptive and easier to use without prior knowledge of endpoints.

Use HATEOAS to guide clients through complex or evolving APIs.

Including links in responses reduces hardcoding and tight coupling between client and server.