7 ms·
HTTP APIs have been a huge hit, but HATEOAS hasn't. Nobody does it right, nobody "gets it," everybody must have just misunderstood Roy Fielding's dissertation.
by dfabulich 5y ago
HTTP APIs have been a huge hit, but HATEOAS hasn't. Nobody does it right, nobody "gets it," everybody must have just misunderstood Roy Fielding's dissertation. If only we had a clearer, better explanation, like this one!
Unfortunately, this article demonstrates what the industry has known/shown for years: that HATEOAS is unsuitable as a technique for HTTP APIs.
Imagine writing a programmatic client against the bank account "API" documented in this article, where the way you'd find out that you can't make a withdrawal is not by checking a "status" in JSON and finding it's overdrawn, but by parsing the HTML and noticing that there's no action link (no `<form>` element!!) that happens to make a withdrawal.
Instead of a JSON parser, you'd now need an HTML parser (one of the most notoriously quirky formats in modern use), but not just that, you'd also need your client to read and understand that HTML.
For example, where's the error message explaining why you can't withdraw? Why, it's written in the page as user-visible text. Which text is user-visible? Uh oh, now you need to parse and execute the CSS on the page to figure that out, too.
You'd need a full-blown browser to do that--a "user agent" as the HTML specification likes to call it--and now, instead of using an API, you're screen-scraping the web site by automating a browser with Selenium or Puppeteer or what have you. What will the client do when the server decides to restructure the HTML? Which one of those <a> links or <form> elements represents withdrawing cash??
It is possible to develop useful tools that automate full-blown websites, but it it's much much easier to develop useful clients when the responses are highly limited in the structure they're allowed to return, to couple the client to the server by committing, in advance, to how the API will work.
That's been Fielding's mistake from the very beginning: to think that hypertext provides useful techniques for developing programmatic interfaces. Hypertext is only useful because of its users. Users can read text, understand it, and decide what links to click on or what forms to submit. Programmatic API clients can't afford that luxury.
As the article demonstrates, if the client was intended to just be a program, we would never use HTML for any of these exchanges, and especially not use <a> links or <form> elements to convey to that program what is or is not possible.
The industry has rejected HATEOS not because we were too stupid understand how awesome it is; we've rejected it because we do understand how awesome it isn't.
- recursivedoubts 5y agoI agree entirely with you and I don't regard it as unfortunate at all that this article shows that HATEOAS is unsuitable for JSON HTTP APIs. It is extremely suitable, and, in fact, is simply descriptive, of an HTML-based API, however. A lot of my thinking around this comes from my work on htmx, a tool that turns HTML into a richer hypermedia: https://htmx.org https://htmx.org And I am actively encouraging people to try to split their thinking about JSON Data APIs (RPC) and REST-ful HTML-based systems.
- javajosh 5y agoI agree entirely with you Do you, though? The GP is pointing out that HATEOAS (terrible name btw -- why not just HAS, Hypertext Application State?) requires a full, stateful user agent for a client to consume the "API", whether human or otherwise. This is what we call "screen-scraping", and it's a pretty tough road to consume an API like that. In particular the GP points out that an interaction requires, in general, a (stateful) crawl of the remote. Note that screen-scraper issues boil down to state (which the GP covered) or "entropy" -- HTML is higher entropy than JSON, and programmers prefer to use the lowest entropy thing, because its much easier to work with, in exactly the same way text is easier to work with than a jpg of text. What JSON driven SPAs are doing is reifying hypermedia using a static function that maps from JSON to HTML -- and that function IS coupled to the domain. And I would argue you can't get away from that as long as you want to decouple presentation from state - and it seems like HAS wants to explicitly couple them, which is bad news for programmatic consumption because it means changing the page layout will change your API, and that's called "brittle" in engineering circles. Interestingly, you could rescue a low-entropy representation in HAS by specifying a (hypermedia-specific) function that does the reverse operation of the JSON SPA function, and extracts a low-entropy representation of the page. But this would impose constraints on page authoring, so it's not exactly without cost.
- brabel 5y agoA HATEOAS API is one where the client is completely un-coupled to the server and any domain in particular... you want to have a front-end that consumes an API, that's the opposite of that. You and many others in this thread seem to think that an API must be separate from the front-end, which is understandable as that's the current standard way to do things, but HATEOAS is the polar opposite of that. The web itself is HATEOAS, so obviously it's useful.... the fact you can build a front-end app that consumes a JSON HTTP API on top of that shows just how incredibly powerful that concept is -but yeah, it requires a smart client, like a browser, to work...