During a discussion on how to return values from an API, I told someone: just use HATEOAS. I had a reaction like “and what is that?”. HATEOAS (Hypermedia as the Engine of Application State) is a constraint of REST APIs that adds an extra layer of information to the responses that allow clients to dynamically discover and navigate the API. HATEOAS provides a more flexible and discoverable API compared to traditional REST queries that require clients to hardcode URLs for each endpoint.

Many people’s reaction reading the above is like “why not using GraphQL then?”. When compared to GraphQL, HATEOAS and GraphQL serve different purposes. GraphQL provides a more efficient and flexible way of querying and manipulating data from an API, allowing clients to retrieve exactly the data they need in a single request. On the other hand, HATEOAS focuses on providing a discoverable API and enabling clients to navigate the API dynamically, without having to hardcode the API’s structure.

When compared to REST, traditional REST queries typically require the client to know the exact URL of the endpoint they want to request data from, and the client needs to send separate requests to retrieve different pieces of data. This can lead to inefficiencies, as the client may need to make multiple round trips to the server to gather all the data it needs.

In contrast, HATEOAS provides additional information in the API response that allows the client to dynamically discover and navigate the API, making the API more flexible and discoverable compared to traditional REST queries. Same way, when calling an API for creation of an object, instead of returning the new ID or returning the new object with details, it would return you the REST URL instead that you can call to get details about the object – you get more than the ID, and less than the object 😀

Similarly, GraphQL provides a more efficient and flexible way of querying data compared to traditional REST queries. With GraphQL, the client can specify exactly what data it needs in a single request, reducing the number of round trips to the server and enabling the client to retrieve only the data it requires.

Overall, both HATEOAS and GraphQL offer improvements over traditional REST queries, with HATEOAS focusing on providing a more flexible and discoverable API and GraphQL providing a more efficient way of querying data.

Various languages do support easy navigation of it – however, you should note, that: this list is not exhaustive, and other libraries may also be available. Additionally, HATEOAS support can often be implemented manually in any language, as it is a design constraint rather than a specific technology.

• C#: WebApi.Hal, HAL-CS
• Java: Spring HATEOAS, JHAL
• Python: Django Rest Framework, Tastypie

HATEOAS is useful in situations where the API clients need to discover and navigate the API dynamically, without having to hardcode the API’s structure. Here are a few examples and use cases:

• SPA (Single Page Application) – An SPA is a web application that updates its content dynamically, without reloading the entire page. HATEOAS can be used to provide the necessary information to the SPA so that it can dynamically navigate and discover the API, without having to hardcode the URLs.
• Mobile Applications – Mobile applications often have limited connectivity and may not have the latest information about the API. HATEOAS can be used to provide the necessary information to the mobile application so that it can dynamically discover and navigate the API, even when the network is slow or unreliable.
• Microservices – In a microservices architecture, the APIs between services are often changed and updated frequently. HATEOAS can be used to provide the necessary information to the client so that it can dynamically discover and navigate the API, even when the underlying implementation changes.
• Versioning – When a new version of an API is released, the URLs and endpoint names may change. HATEOAS can be used to provide the necessary information to the client so that it can dynamically discover and navigate the latest version of the API, without having to hardcode the URLs.

HATEOAS is a widely adopted constraint in RESTful API design and has been used by many companies and organizations. Here are a few examples – many other companies and organizations also use HATEOAS in their APIs. However, specific case studies are not readily available as the usage of HATEOAS is often part of the internal implementation details of an API and is not widely publicized.

• Amazon Web Services (AWS) – AWS uses HATEOAS in many of its APIs, such as the Amazon S3 API, to allow clients to dynamically discover and navigate the API.
• Netflix – Netflix uses HATEOAS in its APIs to allow clients to dynamically discover and navigate the API and to improve the discoverability and flexibility of its APIs.
• Salesforce – Salesforce uses HATEOAS in its APIs to allow clients to dynamically discover and navigate the API and to improve the usability and efficiency of its APIs.
• Twitter – Twitter uses HATEOAS in its APIs to allow clients to dynamically discover and navigate the API and to improve the usability and efficiency of its APIs.