To HATEOAS or not to HATEOAS?

Last Update: 17.10.2017. By Jens in APIs | Learning

Or when is a REST API a REST API? That is the question. And there is no easy answer. Let’s take a closer look.

If you are not familiar with the concept, HATEOAS stands for Hypermedia as the Engine of Application State. It is a constraint in the REST API architecture and helps in decoupling the client from the server. Let’s summarize a REST API briefly:

1. each resource/object has its own URI
2. we interact with a resource/object to retrieve, change or delete
3. on each interaction we exchange the full state of the object/resource
4. resources can link to other resources
5. a client needs only the API base URI to discover all resources
6. no out of bound information is involved; the client gets all knowledge directly from the API
7. it uses Hypermedia
8. the server can change anytime, and the client should not break

The essentials HATEOAS covers are points 4, 5, 6 and 7. So, if a REST API strictly follows the architecture, a REST client needs no prior knowledge about how to interact with it besides a general understanding of hypermedia.

It is also the fighting ground if you can call your REST API a REST API if it does not implement HATEOAS. Interestingly, the most disagreement is the combination of “no out of bound information, ” and the “client needs no prior knowledge”. It boils down to two arguments I constantly read:

1. Don’t call it REST API if it does not implement HATEOAS (pro-HATEOAS advocates)
2. HATEOAS is unrealistic because this type of client does not exist and will not in the near future (contra-HATEOAS advocates)

That’s the situation. Now, let’s spice it up a bit.

I think both statements/arguments are right. I like crystal clear names for things too; it helps people to realize they are talking about the same thing like using the Latin names for muscles. But sometimes it is not that easy for complex things or ideas. In the beginning, they are often not clear, not field tested or involve more components than a simple muscle. Meanings of a simply named complex topic can evolve. That’s the case with the REST API. It took over a decade that people started to actually use fractions of it; to the point, it was useful for them. Unfortunately, they called it REST API because they used part of it, and the name took off with a slightly different meaning. And this newer meaning stayed and even made its way to job descriptions and business (because it was the fancy fad). But we weren’t humans if we could not fight over silly names.

Now to the other statement. I think it has less emotional burden than the naming things. After implementing ways to generate UIs based on dynamic declarations for APIs several times now, I can say it works to a certain, pretty small, degree. If the resource or UI grow in complexity and relations it will not work. It is also a reason why things like XForms never really took off. I guarantee you that your customer will request something that will break your nice design; then you can either deviate from your design or force the feature in it which can turn into a nightmare.

However, HATEOAS doesn’t even cover this aspect. It is navigation of resources only. With it alone, a client could only display the resource and show a set of available action. Meaning is left to the user. Sure, we can extend it with ALPS and HAL to add more meaning for the machine and user. Which brings me to the point that it might be a misconception that these explorable APIs are for the client aka machine. Maybe it is for a developer exploring the API manually.

When we interpret the “prior knowledge” in the meaning of no prior knowledge is needed for navigating the API. That makes more sense. The client would have prior knowledge of the resource and how to display them, etc., but how to find them and which actions are available for a particular resource are defined by the server.

However you interpret it, there is no simple answer to use HATEOAS or not. If it makes sense in a situation, go for it. If it does not add value or makes things more complicated, then don’t use it. Fighting over the name is ridiculous when the common meaning has already changed too far.

What’s your take on it?

Have you ever used HATEOAS in a production system?