HATEOAS: How REST APIs improve the user experience
Constituting the third and final level of the Richardson Maturity Model (or RMM), it is considered the way to create an API that best respects the REST design. Let’s explore this concept together.
One of the most widely used architectures for creating online and mobile applications is REST APIs. Understanding the fundamental concepts behind REST APIs is essential for developers, including the often-overlooked concept of HATEOAS (Hypermedia As The Engine Of Application State), which provides numerous benefits for both users and developers.
Using hyperlinks to express the available resources and activities, it seeks to enhance the overall user experience by making REST APIs more flexible, scalable, and maintainable. Without having to know the API structure beforehand, this method enables clients to dynamically discover API capabilities and navigate between resources. It also makes application maintenance easier by eliminating the need to update links everywhere in the app.
It allows resources to be linked to one another via hyperlinks, allowing for the dynamic discovery of available resources and potential actions from hyperlinks. This is considered as extra conditions to the replies that the REST API must produce.
Let’s take a concrete example:
If you want to provide an API that allows you to search and browse a music library, like Deezer or Spotify for example, the “simple” solution you have is the following:
Several endpoints, one for searching, one for viewing album details, one for viewing artist details, … While this solution works, it requires knowing each of these endpoints, as well as the expected type for each parameter(a code, an id or a hash for example).
By using a HATEOAS system, post connection, we can propose direct access to the user’s playlists and to the search. For each result of the latter, a link to the artist in question, from an artist, the list of his records and why not a top 5 of his music, from a music, a link to the artist, the album, the featuring(s), the producer(s), etc…
Example in “classic” format:
{
"data": [
{
"type" : "artist",
"title" : "Backstreet Boys"
},
{
"type" : "song",
"title" : "Back in Black",
"artists" : ["AC/DC"]
},
{
"type" : "song",
"title" : "Back to Black",
"artists" : ["Amy Whinehouse"]
},
{
"type" : "song",
"title" : "Back that up to the Beat",
"artists" : ["Madonna"]
},
{
"type" : "song",
"title" : "Back To You",
"artists" : [
"Lost Frequencies",
"Elley Duhé",
"X Ambassadors"
]
}
]
}Example with the HATEOAS architecture:
{
"data": [
{
"type": "artist",
"title": "Backstreet Boys",
"links": {
"self": {
"href": "http://127.0.0.1:8080/artist/5rSXSAkZ67PYJSvpUpkOr7"
},
"songs": [
{
"title": "I Want It That Way",
"href": "http://127.0.0.1:8080/songs/47BBI51FKFwOMlIiX6m8ya"
},
{
"title": "Everybody",
"href": "http://127.0.0.1:8080/songs/1di1BEgJYzPvXUuinsYJGP"
},
{
"title": "As Long as You Love Me",
"href": "http://127.0.0.1:8080/songs/3UpS7kBnkVQYG13pDDFTC4"
},
{
"title": "Shape of My Heart",
"href": "http://127.0.0.1:8080/songs/35o9a4iAfLl5jRmqMX9c1D"
},
{
"title": "Quit Playing Games",
"href": "http://127.0.0.1:8080/songs/0Uqs7ilt5kGX9NzFDWTBrP"
}
]
}
},
{
"type": "song",
"title": "Back in Black",
"artists": [
"AC/DC"
],
"links": {
"self": {
"href": "http://127.0.0.1:8080/song/08mG3Y1vljYA6bvDt4Wqkj"
},
"artists": [
{
"title": "AC/DC",
"href": "http://127.0.0.1:8080/artist/711MCceyCBcFnzjGY4Q7Un"
}
]
}
},
{
"type": "song",
"title": "Back to Black",
"artists": [
"Amy Whinehouse"
],
"links": {
"self": {
"href": "http://127.0.0.1:8080/song/3FAclTFfvUuQYnEsptbK8w"
},
"artists": [
{
"title": "Amy Whinehouse",
"href": "http://127.0.0.1:8080/artist/6Q192DXotxtaysaqNPy5yR"
}
]
}
},
{
"type": "song",
"title": "Back that up to the Beat",
"artists": [
"Madonna"
],
"links": {
"self": {
"href": "http://127.0.0.1:8080/song/5ZQ2slXNqImBi0SdomcjYN"
},
"artists": [
{
"title": "Madonna",
"href": "http://127.0.0.1:8080/artist/6tbjWDEIzxoDsBA1FuhfPW"
}
]
}
},
{
"type": "song",
"title": "Back To You",
"artists": [
"Lost Frequencies",
"Elley Duhé",
"X Ambassadors"
],
"links": {
"self": {
"href": "http://127.0.0.1:8080/song/3K00Ib1shkOEiAXU5pec6e"
},
"artists": [
{
"title": "Lost Frequencies",
"href": "http://127.0.0.1:8080/artist/7f5Zgnp2spUuuzKplmRkt7"
},
{
"title": "Elley Duhé",
"href": "http://127.0.0.1:8080/artist/67MNhiAICFY6Pwc2YxCO0K"
},
{
"title": "X Ambassadors",
"href": "http://127.0.0.1:8080/artist/3NPpFNZtSTHheNBaWC82rB"
}
]
}
}
]
}REST APIs can offer a better, more user-friendly experience by doing this. It is simpler to use, especially for users who are not professional developers, because developers who use it don’t need to know the architecture and tree structure of the API beforehand, instead, they simply navigate the hyperlinks offered by the API as they go along. It’s also important to keep in mind that the links returned can vary depending on the context, such as the state of the resource being visited or the role of the person logged in, delivering a personalized user experience based on the requests of each customer.
Going back to our previous example, we may see an administrator-only modification access that standard users will not have, for example:
All users will be able to access the list of songs included in the album, the artists who contributed, and the page listing the musical genres to which it belongs upon calling an album. The album’s data, such as its genre or artist, can be changed by the administrator, who can also add music to the album.
Thus, the management of rights and a large part of the business logic can be deferred to the backend, making the display completely conditional.
Suppose that we have an API for a banking system that offers features like login, balance query, funds transfer, bill payment, etc. Here is how the API can make use of this navigation mode to provide consumers simple navigation:
The login endpoint is the only entry point a user needs to be aware of. When a user attempts to log in to the API, the API may either respond with an error message and a link to the password reset API, or with a response that includes links to the most popular resources, such as balance lookup, money transfer, bill payment, etc.
The API may return a link to a funds transfer endpoint, transfer to a savings or external account, a link to bill payment, etc. If the customer’s balance is sufficient. It can lead to account credit where the user can add funds to their account if their balance is inadequate.
In conclusion, integrating HATEOAS into a banking system can make it easier for users to navigate and support them through the account management process. Links can be made available or unavailable depending on the balance, reducing the likelihood of errors and pointless calls.
The advantages of this system:
You can also make more scalable APIs using HATEOAS. Resources can be added, changed, or removed without having any impact on the consumers who use your API. To access the resources they want, customers only need to request the links supplied. This makes it possible to better separate the front and back ends and to accommodate third-party applications that only use your API. You may, for instance, create fewer pages and programmatically show the components based on the response from the API.
Also, by providing hyperlinks to direct clients to alternative endpoints for resources or actions in the event of an error, it helps simplify error handling in a REST API. When an error occurs, the server may provide in the response a link to comprehensive documentation about it as well as links to additional sources or steps the client can take to help fix the error and prevent blocking of the user. For instance, the server might send a response with an error code and a link to the authentication API if a client tries to access a resource for which it does not have the required rights. This will enable the client to log in and access the resource. Similarly, if a request is improperly formatted, the server may respond with an error message and a link to comprehensive instructions on how to format requests correctly or samples of legitimate requests.
It could appear challenging for novice developers to use HATEOAS. Yet, there are frameworks that makes REST API implementation simpler, such as Spring HATEOAS and ASP.NET Web API, for instance. These frameworks offer resources for handling error responses and hyperlink creation.
Disadvantages:
Even though HATEOAS offers multiple advantages in developing a REST API, it is essential to understand its impact on API performance and optimize accordingly. By requiring the client to navigate through several links before arriving at the desired resource or action, using hyperlinks to represent available resources and actions can increase the number of HTTP requests made to your server. This is because resources that are tucked away behind several navigation layers will also increase the number of server calls. In addition, creating and transmitting hyperlinks can consume additional resources, which can impact API performance, especially for high-load APIs. So, it is crucial to design the navigation path as efficiently as possible, in order to reduce the amount of server calls. Finally, it is important to ensure an efficient API design using caching, paging and data preloading mechanisms to minimize request overhead and reduce resource consumption. In addition, implementing monitoring and load testing mechanisms can help identify bottlenecks and points of failure in the API and quickly correct them to ensure optimal API performance.
Also, there may be security concerns with this architecture that need to be addressed. In fact, a malicious user may be able to navigate the API and access resources or activities for which they do not have the requisite rights due to the usage of hyperlinks to represent resources and actions. For instance, a user can click on a hyperlink to access a resource that is not intended for them, or they might alter the URL to access a resource or perform an action that they are not authorized to perform. Moreover, producing and sending hyperlinks can use up extra resources, which may compromise the security of the API, particularly for sensitive or heavily used APIs.
It is crucial to establish strong security measures for the API, such as user authentication and role validation, input validation, error handling, and real-time API monitoring, in order to handle these new threats. To further safeguard critical resources or API actions, it is advised to set rigorous security guidelines and limit user privileges. At the end of the day, security management using HATEOAS can help to boost user confidence in the API and guarantee the confidentiality, integrity, and availability of API data and resources while offloading the frontend application from this responsibility.
TLDR :
In conclusion, especially for large-scale and scalable projects, the HATEOAS architecture offers several benefits for REST API design. It can be easier to maintain and expand the API over time by using hyperlinks to represent resources and actions. This can also help with dynamic API discovery and flexibility improvements. But it’s crucial to think about how HATEOAS will affect performance and security, as well as the optimal ways to create and use REST APIs with this architecture. This can be a powerful approach for developers trying to establish scalable, user-friendly REST APIs with careful planning and execution. With any luck, this post has given you the knowledge you need to discover this exciting architecture and the tools you need to start creating REST APIs using HATEOAS. Happy exploring!
