Web API Design Part Eight: HATEOAS

08 Aug

Episode 93

Temperatures around are deeply disturbing when I’m writing this post, so I decided to banish myself to a place with air conditioning and cold brew coffee. Time from the last post is a bit longer than expected, but as an excuse, I wrote (almost) two different articles meanwhile on the subject of microservices, that will be hosted on other blogs. I will link them here later. Digression aside, today we are going to talk about Hypermedia as the Engine of Application State, also known under a lovely acronym HATEOAS.


The previous article, about security, has a brief reference to a soundtrack of a classic game Diablo II, and so has the art I used on the slide about HATEOAS on my API design presentation. Remember the boss of act III, Mephisto? Apparently, any serious demon needs an appropriate title, in that case, it was: Lord of Hate. Hate, HATEOAS, you know, it worked well together. Okay, I’m over with digressions, I promise. Let’s get down to Dungeons of Hate… I meant, let’s get down to business.

The Overlord

I meant: The overview… HATEOAS is a part of REST architectural style. It might be considered a high-level part according to Richardson maturity model, as I mentioned in the origins of REST episode. Hyperlinks presence indicates the higher level of RESTfulness after verbs and HTTP nouns usage. The idea is to include hypermedia links representing possible further actions in server responses so that the API client can manipulate the state of the application through them. Theoretically, there is one entry point, and we don’t have to store any other links, we can just follow whatever server gives us. Available actions may change, links may change, but we get that in response body each time, so the client is decoupled from the server. We may think of it as a web browser, where we don’t have to look up in the printed manual the information that products are located under this particular address while user profile is under that address, we just follow the links. While the idea of hypertext is a concept dating back to 1965 and REST has nearly two decades now, hypermedia in web APIs are still not that common, and there is no consensus in the industry how to represent them. Let’s have a look at advantages and drawbacks of HATEOAS before we inspect current tools to implement it.


As I mentioned HATEOAS is a way to further decouple the client from the server, which one of six REST constraints. Theoretically, we are able to implement a flexible client which is much more resistant to changes in the API than clients with hard-coded links are.


Hyperlinks act partially as documentation, as they tell us what we can do assuming the current application state. Hold on, wasn’t all this supposed to be stateless? Well yes, stateless in a sense that we don’t keep a session on the server, however, the state here refers to the business object on the server. For example, we might have created a reservation for a train ticket and as a response, we might get links that will allow us to transform this reservation in a final booking, or cancel it. The booking response might include links to generate PDF tickets etc.

As we receive possible actions in links, if we follow that, we are effectively eliminating the possibility of errors that are results of operations disallowed due to the current state. We can’t perform the booking if there is no prior reservation, for example.

An argument for purist: It’s part of REST. If you don’t have hyperlinks, your API is not fully RESTful.


The generic client premise sounds good on paper, but in practice, if API changes because of new operations, removed operations, restructuring etc., the client most likely will have to change too. HATEOAS does not guarantees our client won’t break.

Hyperlinks are not a substitute of documentation. While certain HATEOAS implementations facilitate linking parts of the documentation, this is not how we usually work with API. We want to have a clear list of all possibilities up front when assessing new API, not discover them through links. Some business flows might be independent so a single point of entry can be an artificial construct. Many business rules governing what’s allowed and what not is impossible to clearly express in hyperlinks. We also still need a documentation to actually understand what those links mean.

Hyperlinks increase the size of the HTTP response. This might be a problem, especially in case if there are many links in relatively small responses and scenarios where we want to conserve bandwidth. It costs CPU and memory on the server side to generate links, and on client memory to handle them. Also, it can be seen as utter redundancy. Hey, I asked you for data. I’m aware what to do with this data, you told me that million times before!


Let’s face it, most clients do not take advantage of HATEOAS, because it requires an additional layer of flexibility in implementation and is difficult in general. Sometimes, we just need to do the shit done, without that much finesse.

Trumping the purist argument: who said your API has to be 100% RESTful? It’s not the only possible architectural style out there.


It seems that angels and demons had quite a fierce battle. Who wins in the end, and should I use HATEOAS after all? The answer is as usual, it depends. On your clients, whether it’s internal or external API, how important the performance is, how complicated are relationships of objects and actions and whether it’s possible to express them in links and other factors. For me, the approximated answer would usually be: ”yes, but…”. Just consider all the demons I mentioned and do what’s best for you.  Let’s now briefly look at some existing implementations of HATEOAS, or hyperlink format so to say.

HAL – or Hypertext Application Language dates back to 2011. It’s quite simple and easy to implement, popular, allows nesting of links, and the inclusion of documentation links via curie mechanism. Supports JSON and XML but formats are a bit different. It was RFC-proposed and is currently the only standard in Spring HATEOAS.

Collection+JSON – designed in 2011, originally to handle collections in JSON, not for HATEOAS. It was widely adopted in the early days of HATEOAS popularity, however, it’s a bit complex and, well JSON only.

Siren – designed in 2012, it resolves around entities, classes, and actions. It’s quite powerful, but not widely adopted.

JSON API – created in 2013 and quickly gaining popularity, it’s easy to implement and provides more than only hyperlinks format, which might be useful too. Still only JSON though.

JSON-LD – or JSON Linked Data is a format designed in 2014, not only for APIs but also for NoSQL databases and focused on linking documents. It’s a bit complicated, but unlike other formats mentioned here, it’s possible to introduce it to already existing API without breaking compatibility. It is recognized by W3C as a standard.



So, which one to choose? Personally, I mostly have experience with HAL, but this is also Spring HATEOAS choice, so we should be happy with that. In modern API, if you don’t care about XML (who cares about XML anymore?), JSON API is probably a good second pick.

There much more formats than mentioned five. My intention was not to provide a full-fledged comparison of HATEOAS format, as I’m on a budget considering the number of words here. I just wanted to give a brief overlord… overview of the idea, present pros, cons and relevant consideration and also have some excuse to include artworks of beasts from hell on a software development focused blog. Probably you are used to non-conventional imagery if you are not a first timer here though. If you like a bit more details, I can recommend an article on hypermedia formats by Mike Stowe, as well as his excellent talk on HATEOAS. Happy demon hunting in your API and stay tuned for the next episode.

Images by:



Posted by on August 8, 2018 in API, Technology


Tags: , , ,

2 responses to “Web API Design Part Eight: HATEOAS

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: