Encounters with the Devil
After processing the trauma that was my thesis, comparing a traditional level 2 REST API with a level 3 REST API, I was suddenly reminded of it by a woman currently working on her own.
HATEOAS as can be deducted from its name, is something filled with pure hate. It is something that holds nothing sacred. It ruins tradition. Hypermedia As The Engine Of Application State - a bogus name and a bogus acronym was first coined by the founder and HTTP IETF spec contributor, the famous Roy Fielding! A round of applause for my dearest friend whose thesis I read and understood little to nothing of.
I should add I am not a hater of Roy Fielding - hell his thesis did not coin the term HATEOAS, instead, a blog post he wrote 8 years later focused more so on the hypertext-driven theme.
I am however mad enough - not thanks to the thesis - I may be the problem actually; however let me rant on.
Evolution Gone Wrong
I understand the point they all tried to make, the back-end should lead the client. The client shouldn’t be telling the back-end what to do. The back-end should instead lead the front-end by displaying which endpoints are available. In theory this sounds amazing. In theory most things sound amazing. Some say practice makes perfect yet I’ve been using my brain for the entirety of my life and I still think I’m stupid.
By pushing this logic to the back-end, one must now manage multiple extra things on the back-end:
- Where you are
- What you did
- Who you are
Now I love me some topical questions just not on the back-end. The back-end now has to process context.
Pure Torture (Implementation)
Imagine (or actually I would rather you do not. Too many have suffered because of HATEOAS) you create a simple forum. People can create posts, edit them and so on. Usually the front-end once you are authenticated will know who you are, and the associated permissions you get with that role. The front-end will hide certain actions that aren’t applicable to you.
With HATEOAS your front-end becomes a parser. You parse the output. Except, no one has made a proper Hypermedia Application Language (HAL). They’re outdated, and are not made for the modern web. Hell, the authors of SIREN tell you to just edit the HAL to fit your needs. Again, the author of a standard, tells you to, change, the standard.
But Lorenzo, my beloved and dearest author, software development is about accommodating changes. IT is! Except when you start doing this with standards that need to be processed, you cannot rely on third-party parsers. You are now also responsible for the parsing. Great, yet another thing. Decoupling? Haven’t heard of him. You now wrote a custom client-side parser for a modified standard. Plug and play? No, we don’t do that here.
Good grief, a software developer has to do their job. Someone be kind and put an end to their misery.
I get the point. I get it, I really do. But that’s not where the misery ends, nor starts. It goes deeper as goes my hatred.
(Security) Benefits
HATEOAS - as foul as it may be to hear, does offer some security benefits. But not in the way you think. Or maybe in the way you think, dear reader I am not you.
As every response that is dictated by the server is tailored to the user, they never discover the actual APIs to the fullest extent (assuming they are not an admin). The front-end knows NOTHING about the back-end architecture. All it knows is how to parse the context.
But is this really security? Or just obscurity? I would argue the latter. You still need to secure the API endpoints from the back-end’s side. An attacker could still guess your endpoints and get access otherwise. Instead with HATEOAS you made some poor developer’s life even worse. Quality of Life. What’s it called when it just diminishes instantly? Inflation? Depression? Spite.
But those aren’t the only “benefits”. HATEOAS allows you to add pages to a website by only editing the back-end. C(B)razy, I am aware. It also means the front-end barely, if ever after initial implementation needs to be edited. However think about it my front-end codemonkeys - is your career really on the brink of extinction purely because Lorenzo said so?
Absolutely not. HATEOAS is not fit for production use.
Paypal uses HATEOAS! What are you saying Lorenzo?
Correct. They do for some of their APIs. I guess I make the same mistakes as multi-billion companies. Where’s my funding round? On a more serious note - I genuinely don’t get why they do it (aside from legacy reasons). They’re a huge website with massive ramifications if their API ever changed out of the blue. The hard-coded level 2 warriors would have a heart attack.
Ah, I see now. It was never about HATEOAS. It was about betraying our values and traditions. Why would the human race ever change something if it works? Why would any developer learn something more complex to implement - oh what do you mean someone mapped the API anyway and isn’t consuming our API in the way we intended?
Complexity
Earlier I mentioned the topical questions, who what where and why am I doing this to myself. But the truth (limitedly so), is that HATEOAS adds a lot of complexity to the codebase. Keeping track of the extra content is generally not worth it. In a world where we deem statelessness as superior why are we suddenly telling the back-end to carry all of its weight? Why are we ‘accommodating’ UI logic in the back-end? If I wanted UI in my back-end I would’ve written Wordpress plugins/PHP for a living.
New Tomfoolery
The worst part of all this? People suggesting AI will magically make HATEOAS better. Not the implementation part, but to discover APIs? Are you kidding me?
Lorenzo you’re making this up. No one knows what HATEOAS is. It’s irrelevant AI developers and engineers and pro max plus thinkers are way ahead of HATEOAS.
I wish I was making this up. I really wish I was. But the people they never stop to amaze me.
I do get what this was hinting at. It would make it easier for generative AI etc to parse API’s since they become self-discovering. However, if your AI agent or whatever you want to call it is exploring APIs this way.. and not with an allow list… you have bigger things to worry about than your API being discoverable. What would even be the purpose of this? Going down API routes? I’ll happily always include a link to a random resource that just goes ad infinitum.. I don’t see the use of this.
Proposed Alternatives
I propose we all become farmers. Live in a small community. Wholesome lives ahead of us. Far from the city. I’ve already picked the names for my chickens and farm dogs.
Yet that reality is not happening just yet, or ever. In the meantime, I suppose we’ll just have to deal with traditional REST APIs. Maybe I should touch GraphQL (or perhaps grass), for my sanity has no boundaries.
On a serious note, purely out of frustration, I would not recommend HATEOAS. Against my supervisor’s wishes, I would just not recommend it. It is not worth your sanity. It works great to impress others - oh yes my thesis was about Hypermedia As the Engine Of Application State - a bunch of words that mean nothing.
At least months of suffering, resulted in a gold star grade of 85%. Was it worth the trouble? Absolutely not. Was it a bribe to stay in the industry and not live my life out on a farm? Maybe.
Should I maybe have focused on GraphQL instead and thrown HATEOAS into a gutter? Most likely. Client-leading the back-end in a very specific way? Could never go wrong. I’m sure there’s no security vulnerabilities with this ever. Oh wait. Right. Reminder, Mongo DB is Web Scale also!