The Trouble with HATEOAS

Do you know what the trouble with HATEOAS is? It’s that we still debate the value of HATEOAS. And that is not to say that it’s value is clear and undeniable. No, we should continuously debate and reevaluate the value of “things” with computing. The trouble is that the debate is almost always discussed in absolute terms. Certainly, for HATEOASphobes it is bad, absolutely. Which leads to people like me, obviously a very rational and clear thinking person, to start sticking up for HATEOAS, absolutely.

And here’s the thing, HATEOAS is simply a (non-optional) constraint of REST. And REST is simply an architectural style. And….

An architectural style does not have pros and cons, in absolute terms. It has characteristics, which may or may not provide value to the problem at hand.

Too often, we want a checklist of when and when not to use a style or pattern. But that’s the wrong question. We should be asking what are the characteristics of the style in question and then we can work out of it’s suitability.

The other problem with HATEOAS is that it’s an ugly acronym that we cannot agree on how to pronounce — for years Linux suffered from the same annoyance for me, but I think we’ve now collectively agreed on it’s pronounciation.

So, the trouble with HATEOAS isn’t really with HATEOAS.

To try to rationalise the discussion in future, let’s do a bit of myth busting about HATEOAS. I’m going to assume all those reading this know what it is, but if not there are plenty of excellent resources that explain it, or I’d suggest reading Jim Webber’s excellent “REST in Practice”.

The Myths

Richardson’s Maturity Model lists levels of REST

One of the first articles I read on the subject of REST was Martin Fowler’s Richardson Maturity Model. The maturity model described was developed by Leonard Richardson and describes three levels of API, with each level adding a characteristic of REST until Level 3 which talk about the HATEOAS constraint. I think it’s a very good resource for learning and understanding REST. However, it’s unfortunately become known to many as the 3 levels of REST. Which leads people to start talking about producing REST at Level 2 (more often that not). But as Martin Fowler himself says at the end of the article:

I should stress that the RMM, while a good way to think about what the elements of REST, is not a definition of levels of REST itself — Martin Fowler

Roy Fielding, who described the style and coined the term, has said HATEOAS is a non-optional constraint of REST. Since it’s his term and description, not sure why would insist on changing its meaning.

Don’t take this as saying doing Level 1 or 2 APIs is wrong. That isn’t the point. It’s simply not REST. And not being REST…well, that’s ok.

HATEOAS is not pragmatic

When discussing whether we should use HATEOAS or not, I’m almost invariably faced with the phrase “Pragmatic REST”, along with the same two articles that use that phrase. It almost always is aligned with Level 2 of the RMM.

I find the phrase infuriating. Unless there is intentional irony from those that use the phrase, I wish people wouldn’t. To suggest a dogmatic approach to anything is pragmatic is hugely contradictory. Pragmatism, is about adapting your approach to the situation at hand. Therefore, pragmatism is in fact the antithesis to dogmatism. And so, to apply the label pragmatic to one particular approach indicates a lack of critical thinking in solution architecture. Not the best trait for an architect.

HATEOAS can absolutely be pragmatic. If it works. And I have seen it work. Returning to an old theme, it’s all about deciding whether it’s characteristics apply to the needs of your platform.

HATEOAS is complex

I’ve never entirely understood this. If the argument is that it requires developing a great deal of logic to present the links, that logic would need developing anyway.

The complexity may also mean that some up front thinking and design is required. And while to an extent this is true, I don’t see that as a bad thing. With the spread of Agile within the industry, there has become a trend of avoiding up front design. I don’t blame this on Agile (as is clear when reading the manifesto and principles) but an interpretation of those principles. Giving yourself a little time to think things through before committing your code will often save a lot of time. But one of the things about HATEOAS that I like is that you can get it wrong, fix it later and impact is minimised through the looser coupling it affords you.

And when it comes down to it, HATEOAS really isn’t that complex an idea. Some links in a payload that describe state. Done.

HATEOAS is unproven technology

HATEOAS is often described as unproven or cutting edge or some other term used to highlight to people that no one knows whether it will work. But HATEOAS isn’t a technology. And nor is it reliant on unproven technology. In fact, you can implement HATEOAS today with your existing technology. It’s not bleeding edge or unproven. It’s simply one way of doing things with the technology at hand.

However, maybe it’s an unproven way of doing things…

HATEOAS is not implemented by anyone

This is a fair challenge. If you are not a technology company whose reputation is reliant on being a tech leader, then being one of the first to implement something is usually inadvisable. I always ask that question. Has anyone implemented it before?

When it comes to HATEOAS, the likes of Facebook and Twitter and others are used as examples of companies that have public APIs but do not use HATEOAS. eBay and Uber implement a style of API closer to that of the RMM level 2.

But there are plenty of companies that do use HATEOAS. My personal favourite is Paypal, but you also have Github, Visa, Stormpath and how about AWS Appstream. They all do it in slightly different ways, but they all do it.

End of my love letter to HATEAOS

If you have got this far you’re probably now thinking that this whole post has been a love letter to this most controversial, froth-inducing constraints of REST. And that simply underlines the trouble wit HATEOAS. To defend HATEOAS in general terms against the haters, you can end up sounding like a lover or “RESTafarian”. You come across someone blinded to the faults of the style.

And no matter how much I say that HATEOAS is not the answer under all circumstances, always, you still sound like a crazed fool.

The truth is, I am a fan. I think it’s a very elegant solution to a number of architectural problems. It ensures business logic is encapsulated within the API, with no leaking. It allows for looser coupling. It minimises the need for documentation. I can also, through experience, safely say that for standard organisations API needs it is a workable solution.

Whether or not it’s the best solution for a specific problem, can only be determined by those closest to the problem. And that is essentially what good architects are all about.

Show your support

Clapping shows how much you appreciated Reda Hmeid’s story.