HATEOAS: Hypermedia as the Engine of Application State

Seriously, has anyone ever made a non-toy implementation conforming to the idea of HATEOAS?<p><i>A REST client needs little to no prior knowledge about how to interact with an application or server beyond a generic understanding of hypermedia.</i><p>Nothing but a generic understanding of hypermedia? You need some substantial understanding of language and the world to figure out where this link will take you.<p><i>&lt;a href=&quot;&#x2F;accounts&#x2F;12345&#x2F;close-requests&quot;&gt;close-requests&lt;&#x2F;a&gt;</i><p>Sure, English is not my first language and financial terms are probably a real weak spot, but I have at best a vague idea what this will do. Can I request to close my account? But why would I need requests for that, plural? So maybe it is not about closing my account but instead a close request is some financial term? If it is, I still have no idea what it is good for.<p>For consumption by humans, developers poking around in a new API, HATEOAS might be nice. But how on earth are you going to write software that can consume such an API, dynamically discover, understand and use available operations? Maybe you could use ChatGPT to do this. And how are you going to build an UI for this that is any better than what naked objects [1] can deliver if you do not even know which operations the API has to offer?<p>[1] <a href="https:&#x2F;&#x2F;de.wikipedia.org&#x2F;wiki&#x2F;Naked_Objects" rel="nofollow noreferrer">https:&#x2F;&#x2F;de.wikipedia.org&#x2F;wiki&#x2F;Naked_Objects</a>

I am the author of this article.<p>I see a lot of people saying &quot;HATEOAS doesn&#x27;t work&#x2F;has anyone ever used it&quot;.<p>The answer is YES: the world wide web and any traditional web 1.0 application uses it quite successfully. The important thing to realize is that an HTML-based web server <i>is</i> providing an API: a <i>hypermedia-based</i> API. It is providing it to a <i>hypermedia client</i>, namely the browser.<p>The concept has not mapped well to JSON-based data APIs because those APIs are not typically consumed by REST-ful clients. Or, if they are as in an SPA, the hypermedia functionality of the client is ignored in favor of a thick-client approach.<p>We have written a book on the idea of a hypermedia system that explains this in far more detail:<p><a href="https:&#x2F;&#x2F;hypermedia.systems" rel="nofollow noreferrer">https:&#x2F;&#x2F;hypermedia.systems</a><p>which stresses the <i>systemic</i> nature of hypermedia when building a distributed application.

Worth reading this: <a href="https:&#x2F;&#x2F;twobithistory.org&#x2F;2020&#x2F;06&#x2F;28&#x2F;rest.html" rel="nofollow noreferrer">https:&#x2F;&#x2F;twobithistory.org&#x2F;2020&#x2F;06&#x2F;28&#x2F;rest.html</a><p>&gt; REST purists often complain, for example, that so-called REST APIs aren’t actually REST APIs because they do not use Hypermedia as The Engine of Application State (HATEOAS). Fielding himself has made this criticism. According to him, a real REST API is supposed to allow you to navigate all its endpoints from a base endpoint by following links. If you think that people are actually out there trying to build REST APIs, then this is a glaring omission—HATEOAS really is fundamental to Fielding’s original conception of REST, especially considering that the “state transfer” in “Representational State Transfer” refers to navigating a state machine using hyperlinks between resources (and not, as many people seem to believe, to transferring resource state over the wire).8 But if you imagine that everyone is just building FIOH [author&#x27;s acronym for &quot;Fuck It, Overload HTTP&quot;] APIs and advertising them, with a nudge and a wink, as REST APIs, or slightly more honestly as “RESTful” APIs, then of course HATEOAS is unimportant.

&gt;<i>While attempts have been made to impose more elaborate hypermedia controls on JSON APIs, broadly the industry has rejected this approach in favor of simpler RPC-style APIs that forego HATEOAS and other elements of the REST-ful architecture.</i><p>Because HATEOAS is basically useless for machines, and industry runs on machines.<p>It&#x27;s fine when you&#x27;ve got a human clicking things that they&#x27;re looking at, but there&#x27;s no reliable way to reinterpret it for a different use because it&#x27;s so wildly context sensitive in ways that only humans understand. <i>Meaning</i> of things in HATEOAS may be &#x2F; is intentionally allowed to be communicated by non-structured text that accompanies the actions, as literally every example in this page shows.<p>If you&#x27;re doing anything but rendering it for humans to interpret, that flexibility makes it basically impossible. Or binds you to a single output structure, with no way to structurally verify if changes are relevant or not.

I&#x27;ve done the HATEOAS thing as much as possible. Links were rendered in json like the site claims not to do. There is json-ld, of course, but that was just too much, so I didn&#x27;t bother.<p>Can also do a nice trick of rendering nicely formatted json objects in html with proper links if a browser is requesting html&#x2F;text. For an extra bonus split the page and render the docs right next to it, too. If application&#x2F;json is requested, return just json to be consumed by programmatic clients.<p>That said, while it was really nice to learn and navigate the API from the browser that way, none of the programmatic clients ever used the &quot;auto-discovery&quot; feature. They jumped right to the resource the needed and didn&#x27;t bother with the links.<p>At this point REST is just whatever most popular companies designed and called &quot;REST-ful&quot; is what REST-ful became. As much as Roy wants to claim it&#x27;s not &quot;pure&quot; enough, the ship has sailed so speak.

Articles talking about &quot;REST&quot; and &quot;HATEOAS&quot; really need to define &quot;client&quot;. Do they mean a person? Do they mean a web browser? Do they mean an application performing actions autonomously?<p>&gt; A REST client needs little to no prior knowledge about how to interact with an application or server beyond a generic understanding of hypermedia.<p>If in this instance, &quot;REST client&quot; means an application performing actions autonomously, I don&#x27;t see how this statement could possibly be true. Someone writing a client will need to know how the server is going to return responses to requests. It needs to know what operations the server supports.<p>It really seems like REST and HATEOAS, using the strictest definitions, really just mean server-side HTML rendering, which is nothing new. I figured we swapped to client-side rendering (And therefore, servers sending XML or JSON, and the client handles putting it into the page) to reduce server-side loads and the cost of increased CPU usage client-side.

&gt; A REST client needs little to no prior knowledge about how to interact with an application or server beyond a generic understanding of hypermedia.<p>This language always bothered me, &#x27;client&#x27; in this case surely means a advanced general intelligence, or &#x27;human&#x27;, who can futz around with the URIs to try and get what they need. Maybe that&#x27;s better than CORBA, but it&#x27;s not the Universal Translator of interfaces by a long shot.

For me, this feels worse than wikipedia using JSON as an example.<p>JSON isn&#x27;t a great HTMl representation, and the wikipedia examples are definitely missing details about how the underlying API is used. But extremely simple HTML just feels worse.<p>Both pages use a bank account as the example, but my actual bank account has dozens of actions available and is certainly modeled in a way that wouldn&#x27;t be intuitive for people. Which means we&#x27;ve got an example that isn&#x27;t easily parseable by computers, because we have mixed labels and data in the HTML, and isn&#x27;t useful for human beings due to how complex real world entities are.<p>I genuinely can&#x27;t tell if this is like monads (which are useful, but often poorly explained) or if this is just a bad idea.

Is it me who does not understand what HATEOAS is?<p>Always thought that it was basically each server generated page providing the list of links&#x2F;actions that was allowed from then on.<p>Basically a lazy, incremental, and fine grained API.<p>The issue being that it might not be very useful since links have to persist in general on the web. (maybe I misunderstand and it&#x27;s a non issue?) whereas HATEOAS would be useful if links were never shared: then they could be dynamically generated or updated?

I think this article is focusing a lot of attention on a rather arbitrary aspect of web apps, and suggesting some bad conclusions.<p>Taking the example from the article... if you want to present bank account information to a user and allow them to take actions on it, then focusing on HTML (and CSS) is a great idea.<p>However, the data is going to be stored somewhere, and you&#x27;re going to want to retrieve it and transform it into the desired presentation HTML for your app. In the case of the article, you could say describe these two operations abstractly like this:<p><pre><code> retrieveAccountInfo(dataSource) -&gt; (accNo, balance, status) presentAccount(accNo, balance, status) -&gt; HTML </code></pre> so the page HTML is determined like this:<p><pre><code> presentAccount(retrieveAccountInfo(dataSource)) </code></pre> In the &quot;hypermedia&quot; option from the article these two operations run server side in an unspecified way, while for the &quot;rest&quot; option retrieveAccountInfo is implemented as at HTTP GET returning JSON and presentAccount runs in the browser.<p>presentAccount is just as logically coupled to retrieveAccountInfo in the &quot;hypermedia&quot; case as it is in the &quot;rest&quot;, and possibly somewhat more coupled in terms of infrastructure, depending on what&#x27;s going on at the application server. The application state is determined in exactly the same way.<p>Of course, there are tradeoffs between running application code server side vs client side. But it really has nothing to do with hateoas and decoupling, and the article doesn&#x27;t touch on it. (One of the big advantages to running the app server-side is that there&#x27;s no need for client-side javascript -- this makes the htmx approach -- where the app runs server side but you also need client-side javascript -- a bit questionable, IMO.)

What I don&#x27;t get about these examples is how the HTML from the responses should actually be rendered. I assume no frontend would want to render the HTML as is. Hence they would need IDs on those DIVs to style and place them. But wouldn&#x27;t that require out of band information too?

This article makes a mistake calling RMM0-2 APIs „JSON APIs“. JSON is data format just like HTML, XML or protocol buffers and it can be used both by true REST or RPC APIs. Focus on JSON is indeed what makes this article ineligible for Wikipedia, it’s just the wrong angle to look at the subject.

I agree with the fundamental principle that &quot;true&quot; HATEOAS is desirable, and that HTML provides it while JSON doesn&#x27;t.<p>That said, I don&#x27;t quite agree with the criticism of out-of-band information. Is the HTML spec not out-of-band information?<p>Likewise, if they had used an SGML api as the example instead of HTML, would not all the same criticisms of the JSON, for not being HATEOAS, be valid?<p>There are already many JSON-based APIs on the right path like ActivityPub, JSON-LD, and others. Having to know the specs of these things is no more out-of-band than knowing HTML.<p>TL;DR: SGML:HTML::JSON:XXXX. If we can all agree on a good XXXX instead of freeforming from just JSON every time, we can get closer to HATEOAS.

The theory behind HATEOAS was bullshit until LLMs made smart clients plausible. But LLMs don’t need HATEOAS to discover an API. So turns out HATEOAS is still bullshit.

The REST paper was not worth a PhD

It’s possible that in the age of LLMs this stops being a silly idea, but let’s not pretend it hasn’t up until now been a very silly idea.