What is HATEOAS and why is it important for RESTful APIs?

Published in

ReDive

5 min readOct 30, 2023

HATEOAS stands for Hypermedia as the Engine of Application State. It is one of the constraints of the REST architectural style that defines how clients and servers should interact over the web.

The idea behind HATEOAS is that a client should be able to navigate and manipulate the resources of an application by following the links and actions provided by the server in each response. The client does not need to know the structure or details of the API beforehand, as the server dynamically guides the client through the application state transitions.

This approach has several benefits for both the client and the server:

It decouples the client from the server, allowing the server to evolve its API without breaking existing clients. The server can change its resource URIs, add new features, or modify its business logic without affecting the client’s behavior. The client only needs to follow the links and actions that the server provides at runtime.
It simplifies the client’s logic, as it does not need to hardcode any API endpoints or construct complex URIs. The client can rely on the server to provide all the relevant information and options for each resource. The client can also discover new capabilities or resources as they become available on the server.
It improves the usability and discoverability of the API, as it provides a self-documenting and consistent way of accessing and manipulating resources. The client can easily understand what each resource represents, what actions are possible, and what are the consequences of each action. The client can also explore the API by following the links and actions that interest them.

How to implement HATEOAS in a RESTful API?

There are different ways to implement HATEOAS in a RESTful API, depending on the media type and format that are used to represent resources. Some common examples are:

JSON: JSON is a popular format for exchanging data over the web, but it does not have a standard way of expressing links or actions. However, there are some conventions or specifications that can be used to add HATEOAS features to JSON responses, such as HAL, JSON-LD, JSON:API, or Siren. These specifications define how to include links, actions, metadata, and embedded resources in a JSON response. For example, this is how a HAL response might look like:

{
  "id": "10",
  "fName": "Dennis",
  "lName": "Ritchie",
  "age": "46",
  "_links": {
    "self": {
      "href": "/demoApp/employees/10"
    },
    "designation": {
      "href": "/demoApp/employees/10/designations"
    }
  }
}

XML: XML is another common format for exchanging data over the web, and it has some advantages over JSON, such as namespaces, schemas, and validation. XML also has some standard ways of expressing links or actions, such as [XLink], [XForms], or [Atom]. These standards define how to include links, actions, metadata, and embedded resources in an XML response. For example, this is how an Atom response might look like:

<entry xmlns="http://www.w3.org/2005/Atom">
  <id>10</id>
  <title>Dennis Ritchie</title>
  <content type="xhtml">
    <div xmlns="http://www.w3.org/1999/xhtml">
      <p>Age: 46</p>
    </div>
  </content>
  <link rel="self" href="/demoApp/employees/10"/>
  <link rel="designation" href="/demoApp/employees/10/designations"/>
</entry>

HTML: HTML is the most widely used format for displaying web pages, and it has native support for hypermedia features, such as links, forms, images, videos, etc. HTML can be used to implement HATEOAS in a RESTful API by returning HTML representations of resources that include links and forms for navigation and manipulation. For example, this is how an HTML response might look like:

<html>
<head>
  <title>Dennis Ritchie</title>
</head>
<body>
  <h1>Dennis Ritchie</h1>
  <p>Age: 46</p>
  <a href="/demoApp/employees/10">Self</a>
  <a href="/demoApp/employees/10/designations">Designation</a>
</body>
</html>

How does HATEOAS improve security in APIs?

HATEOAS can improve security in APIs by reducing the exposure of sensitive information and preventing unauthorized access to resources. Some of the ways that HATEOAS can achieve this are:

Hiding the internal structure and implementation details of the API from the client. The client does not need to know or construct the URIs of the resources, as they are provided by the server dynamically in each response. This makes it harder for malicious clients to guess or manipulate the URIs and access resources that they are not supposed to.
Providing fine-grained and context-sensitive access control to the resources. The server can decide what links and actions to include in each response based on the identity, role, and permissions of the client. This way, the client only sees and interacts with the resources that they are authorized to access. For example, a customer may see a link to update their profile, but not a link to delete their account.
Enforcing state transitions and business rules on the server side. The client cannot perform arbitrary actions on the resources, as they have to follow the links and actions that the server provides. This ensures that the client respects the constraints and logic of the application state, and does not violate any security policies or business rules. For example, a client cannot cancel an order that has already been shipped, as the server will not provide a link for that action.

Conclusion

HATEOAS is a key concept of the REST architectural style that enables clients and servers to interact over the web in a flexible and dynamic way. By following the links and actions provided by the server in each response, the client can navigate and manipulate the resources of an application without prior knowledge or hardcoding of the API. This improves the decoupling, simplicity, usability, and discoverability of the API, and allows the server to evolve its API without breaking existing clients. HATEOAS can be implemented in different ways, depending on the media type and format that are used to represent resources. Some common examples are JSON, XML, and HTML.

I hope you enjoyed this blog post about HATEOAS. If you have any questions or feedback, please leave a comment below. Thank you for reading! 😊

What is HATEOAS and why is it important for RESTful APIs?

How to implement HATEOAS in a RESTful API?

How does HATEOAS improve security in APIs?

Conclusion

Written by Hari Prasad