2 ms·

I 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 su

I 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 ago
I 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 ago
  A 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...
  - javajosh 5y ago
    It's not that I don't get it, it's that I call HAS screen scraping and I think screen scraping is a bad API design. It's also that I think HAS explicitly couples API and presentation, which is undesirable. We can argue all day, but the proof is in the pudding: build something real with this approach, and show me it's better. I have doubts, but even one counter example would change my mind.
- chriswarbo 5y ago
  > This is what we call "screen-scraping", and it's a pretty tough road to consume an API like that. That's hyperbole. If you're willing to accept clients which are hard-coded to some specific JSON structure, then we can accept clients which are hard-coded to some specific HTML structure. The point is that a HATEOAS API will, by default and with no extra work from anyone, be browsable via any Web browser (including those with assistive tech like screen readers, etc.). In contrast, the best we have for JSON APIs is to pretty-print the response text, perhaps with syntax highlighting; embedded URLs might be made clickable, but we're probably restricted to only performing GETs. If we use HATEOAS this might actually be enough for our purposes; e.g. if we just want to expose some basic functionality, like an admin UI. If not, we can write a client for that API; again, this doesn't require screen-scraping, or solving ambiguous parse issues, etc. since the client is not a general Web browser. If we use JSON, we are pretty much forced to build a bespoke client for the API; due to how little we get 'by default'.
  - javajosh 5y ago
    > [Comparing HAS consumption to screen-scraping] That's hyperbole. How does it differ, then? Do you have any code examples? Based on your next statement: If you're willing to accept clients which are hard-coded to some specific JSON structure, then we can accept clients which are hard-coded to some specific HTML structure it does not differ, but you instead say that both approaches require hard-coded clients to consume programmatically, so they are equivalent. If that were so, then another approach like embedding results in a jpg, would be equally valid since you just have to hard-code your clients to extract information from the jpg. After all the human can parse this so we don't need a bespoke client. From the perspective of theoretical movement of data from a to b, yes of course this is true. But from the perspective of an engineer consuming it, no, they are very different. And the difference is that entropy is proportional to developer pain. I hope you try to be more rational and less ideological about your ideas. I'll leave it at that. I really like thinking about alternative architectures, but this one's appeal seems to rely on ignoring some very real trade-offs.
    - chriswarbo 5y ago
      > Do you have any code examples? For extracting known elements from HTML that's under our control? That's a pretty standard task; here's a shell command to extract the 'deposits' URL from the article's example code: xidel -q -e '//a/@href' - | grep '/deposits' How on Earth is that equivalent to OCRing a JPEG? > I hope you try to be more rational and less ideological about your ideas. What's "ideological" about claiming that it's easy to parse known elements from (X)HTML that we control?

javajosh 5y ago

I 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 ago
A 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...
- javajosh 5y ago
  It's not that I don't get it, it's that I call HAS screen scraping and I think screen scraping is a bad API design. It's also that I think HAS explicitly couples API and presentation, which is undesirable. We can argue all day, but the proof is in the pudding: build something real with this approach, and show me it's better. I have doubts, but even one counter example would change my mind.
chriswarbo 5y ago
> This is what we call "screen-scraping", and it's a pretty tough road to consume an API like that. That's hyperbole. If you're willing to accept clients which are hard-coded to some specific JSON structure, then we can accept clients which are hard-coded to some specific HTML structure. The point is that a HATEOAS API will, by default and with no extra work from anyone, be browsable via any Web browser (including those with assistive tech like screen readers, etc.). In contrast, the best we have for JSON APIs is to pretty-print the response text, perhaps with syntax highlighting; embedded URLs might be made clickable, but we're probably restricted to only performing GETs. If we use HATEOAS this might actually be enough for our purposes; e.g. if we just want to expose some basic functionality, like an admin UI. If not, we can write a client for that API; again, this doesn't require screen-scraping, or solving ambiguous parse issues, etc. since the client is not a general Web browser. If we use JSON, we are pretty much forced to build a bespoke client for the API; due to how little we get 'by default'.
- javajosh 5y ago
  > [Comparing HAS consumption to screen-scraping] That's hyperbole. How does it differ, then? Do you have any code examples? Based on your next statement: If you're willing to accept clients which are hard-coded to some specific JSON structure, then we can accept clients which are hard-coded to some specific HTML structure it does not differ, but you instead say that both approaches require hard-coded clients to consume programmatically, so they are equivalent. If that were so, then another approach like embedding results in a jpg, would be equally valid since you just have to hard-code your clients to extract information from the jpg. After all the human can parse this so we don't need a bespoke client. From the perspective of theoretical movement of data from a to b, yes of course this is true. But from the perspective of an engineer consuming it, no, they are very different. And the difference is that entropy is proportional to developer pain. I hope you try to be more rational and less ideological about your ideas. I'll leave it at that. I really like thinking about alternative architectures, but this one's appeal seems to rely on ignoring some very real trade-offs.
  - chriswarbo 5y ago
    > Do you have any code examples? For extracting known elements from HTML that's under our control? That's a pretty standard task; here's a shell command to extract the 'deposits' URL from the article's example code: xidel -q -e '//a/@href' - | grep '/deposits' How on Earth is that equivalent to OCRing a JPEG? > I hope you try to be more rational and less ideological about your ideas. What's "ideological" about claiming that it's easy to parse known elements from (X)HTML that we control?