6 ms·

Because HATEOAS is stupid for client-server communication. It mandates discoverability of resources, but no sane client will go around and request random serve

by janci 4y ago

Because HATEOAS is stupid for client-server communication. It mandates discoverability of resources, but no sane client will go around and request random server-provided urls to discover what is available. On the other hand, it does not provide means to describe semantics of the resource properties, nor its data type or structure. So the client must have knowledge on the resources structure beforehand. Under HATEOAS the client would need to associate the knowledge of resource structure with a particular resource received. A promising identifier for this association would be the resource collection path, i.e. the URL. If the client needs to know the URLs, why have them in the response? Other problems include creating new resource - how the client is supposed to know the structure of to-be created resource, if there is none yet? The client has nothing to request to discover the resource structure and associations. Also hypertext does not map well to JSON. In JSON you can not differenciate between data and metadata (i.e. links to other resources). To accomodate, you need to wrap or nest the real data to make side-room for metadata. Then you get ugly and hard to work with JSON responses. It maps pretty good to XML (i.e. metadata attributes or metadata namespace), but understandably nobody wants to work with XML. And the list goes on and on.

zozbot234 4y ago
> On the other hand, it does not provide means to describe semantics of the resource properties Yup, wouldn't it be nice to have some sort of standardized framework to describe those resources? You could perhaps call it a Resource Description Framework, or RDF if you like acronyms.
- janci 4y ago
  Aaaand we are back to XML. I don't think XML or RDF is particulary bad for APIs, but they are overly complex and that makes them unpopular.
  - mdaniel 4y ago
    FWIW, JSON-LD allows one to avoid XML but still gain the benefits of RDF, but I hear you about the "complex" part so ultimately it's like the other commenters have said: is it solving a problem your API and userbase has or not?
    - zozbot234 4y ago
      How is RDF (sans XML) overly "complex"? Much of it falls out quite naturally from the choice of building data interchange on hyperlinks to resources, similar to human-readable hypertext.
      - mdaniel 4y ago
        Sorry, I didn't mean that I personally find it complex, merely that I've worked in enough "wwwaaah, software is hard, right-click-y, push" organizations to appreciate why GP would use the word complex and would find friction in rolling out a sane data structure The only leverage I've ever found for using good data structures is when I can demonstrate they solve a "today" pain point, because money/management DGAF about tomorrow anything, and only the tinyest fuck about customer pain so long as the checks clear
  - zozbot234 4y ago
    RDF does not depend on XML. You can use JSON-LD or text-based syntax (N3, TURTLE or extensions thereof) and those are preferred in modern applications.
janci 4y ago
Cont.: Because using HTTP verbs and status codes is stupid too: - the API is then tied to single "transport" protocol (it is application layer protocol in ISO/OSI but if you are not building a web browser, your application should reside one layer upwards) - it crosses ISO/OSI layer boundaries (exposes URLs in data, uses status codes for application error reporting, uses HTTP headers for pagination etc.) I think the second issue is vastly underrated. Protocols that cross layer boundaries are source of trouble and require tons of workarounds. Do you remember how FTP does not work well with NATs? It's because it exposes IPs and ports - transport layer concepts on application layer. SIP? The same thing. With true REST you can build only HTTP APIs, no websockets, no CLIs, no native libraries.
- derefr 4y ago
  > exposes URLs in data That's, uh, the point. Without that, it's not "the web." (And yes, properly-structured APIs are part of "the web" — e.g. the first page of your paginated resource can be on one server, while successive pages are on some other archival server.) This is the whole reason for doing HATEOAS: there's no longer a static assumption that you're working against some specific server with a specific schema structure in place. Rather, your API client is surfing the server, just like you're surfing HN right now. > no websockets Correct in a nominal sense, but not in any sense 99% of developers would care about. Instead of RPC over websockets, do REST. Instead of subscriptions over websockets, do REST against a subscription resource for the control-plane, and then GET a Server-Sent Events stream for the data-plane. Perfectly HATEOAS compliant — nobody ever said resource-representations have to be finite.
  - janci 4y ago
    > This is the whole reason for doing HATEOAS. Seems like a premature optimization to me. Building all applications so that they potentially could be distributed over multiple servers. YAGNI.
    - zach_garwood 4y ago
      Hello, this is the internet, have you heard of us?
derefr 4y ago
> but no sane client will go around and request random server-provided urls to discover what is available Compare and contrast: what SQL admin GUI clients do to discover the DBMS schema. They essentially spider it. > Under HATEOAS the client would need to associate the knowledge of resource structure with a particular resource received. A promising identifier for this association would be the resource collection path, i.e. the URL. If the client needs to know the URLs, why have them in the response? The client does not need to know the URL; the client needs to know how to get to the URL. Have you ever written a web scraper, for a site that doesn't really enjoy being scraped, and so uses stuff like CSRF protection "synchronizer tokens"? To do/get anything on such a site, you can't just directly go to the thing; you have to start where a real browser would start, and click links / submit forms like a browser would do, to get there. HATEOAS is the idea that APIs should also work that way: "clicking links" and "submitting forms" from some well-known root resource to get to the API you know about. As with a scraper, it's the "link text" or the "form field names" — the delivered API — that you're assuming to be stable; not the URL structure. > Other problems include creating new resource - how the client is supposed to know the structure of to-be created resource, if there is none yet? The client has nothing to request to discover the resource structure and associations. What do you think HTML forms are, if not descriptions of resource templates? When you GET /foos, why do you think the browser result is a form? It's a description of how to make a foo (and, through the submit attribute, a place to send it to get it made.) Alternately, compare/contrast what Kubernetes does — exposes its resource schemas as documents, living in the same resource-hierarchy as the documents themselves live. > Also hypertext does not map well to JSON. In JSON you can not differenciate between data and metadata (i.e. links to other resources) It's right in the name: in HATEOAS, hypertext is the engine of application state. Hypertext as in, say, HTML. JSON is not hypertext, because it's not text — it's not a markup language like SGML/XML/HTML are. You realize that HTML is machine-readable, right? That you can respond to an XHR with HTML, and then parse it using the browser (or API client's) HTML parsing capabilities, just like you can receive and parse JSON? That there's nothing stopping you from using a <table> to send tabular data, etc.? And that if you do so, then debugging your API becomes as simple as just visiting the same link the API client is visiting, and seeing the data rendered as HTML in your browser?
- janci 4y ago
wwweston 4y ago
> no sane client will go around and request random server-provided urls to discover what is available. "Random" isn't what's supposed to happen. You hit a top level endpoint, and then at that point other endpoints are made manifest, and then the UA/client and the user decide together what the next relevant endpoint is. And this is what happens all the time with the most common client (the browser). Seems to have worked more or less for 30 years. As for what semantics the UA/client is capable of exploring and providing assistance with: who knows what's possible with additional heuristics + machine learning techniques? > Also hypertext does not map well to JSON... It maps pretty good to XML... understandably nobody wants to work with XML. I don't understand that, actually. Markup is underrated for data exchange potential these days. JSON is frequently (though not always) somewhat lighter on bandwidth and often briefer to type for the same underlying reasons, but beyond that there's no inherent advantage. It just became the easiest serialization/deserialization story, half out of riding the way that JS won, half out of what it didn't bother to try doing (a lot of the meta/semantics) and so gave devs permission to stop thinking about.
- janci 4y ago
  > You hit a top level endpoint, and then at that point other endpoints are made manifest, and then the UA/client and the user decide together what the next relevant endpoint is. That's not how APIs are used. APIs consume and provide data. Raw data is unsuitable to be presented to the user. That's why HTML has so many formatting options. Formatting information is completely missing from APIs. > Seems to have worked more or less for 30 years. Yes, worked for good old web. In this sense, true REST is nothing new and even seems backwards. If we try to do REST while keeping data and presentation separate, we will come to something very similar to XML for data + XSLT for formatting. Or XForms. Old ideas all over again. > I don't understand that, actually. Markup is underrated for data exchange potential these days. XML/markup does not map well to basic data types in current programming languages. These work with strings, ints, floats and arrays/dictionaries thereof. Not Nodes, Elements and attributes of unknown/variant data types.
  - kortex 4y ago
    > XML/markup does not map well to basic data types in current programming languages. These work with strings, ints, floats and arrays/dictionaries thereof. Not Nodes, Elements and attributes of unknown/variant data types Exactly. Arrays are pretty much the most primitive computer data structure (aside from primitives), and the contortions XML must go through to express them is remarkable. So much ceremony, and it can't do a simple list. XML has this core implicit assumption that everything ought to be an object, and I think this was the ultimate death knell for it. You can add complexity to JSON (e.g. JSON-LD) but you can't take the complexity out of XML.

by janci 4y ago

zozbot234 4y ago

> On the other hand, it does not provide means to describe semantics of the resource properties Yup, wouldn't it be nice to have some sort of standardized framework to describe those resources? You could perhaps call it a Resource Description Framework, or RDF if you like acronyms.

janci 4y ago
Aaaand we are back to XML. I don't think XML or RDF is particulary bad for APIs, but they are overly complex and that makes them unpopular.
- mdaniel 4y ago
  FWIW, JSON-LD allows one to avoid XML but still gain the benefits of RDF, but I hear you about the "complex" part so ultimately it's like the other commenters have said: is it solving a problem your API and userbase has or not?
  - zozbot234 4y ago
    How is RDF (sans XML) overly "complex"? Much of it falls out quite naturally from the choice of building data interchange on hyperlinks to resources, similar to human-readable hypertext.
    - mdaniel 4y ago
      Sorry, I didn't mean that I personally find it complex, merely that I've worked in enough "wwwaaah, software is hard, right-click-y, push" organizations to appreciate why GP would use the word complex and would find friction in rolling out a sane data structure The only leverage I've ever found for using good data structures is when I can demonstrate they solve a "today" pain point, because money/management DGAF about tomorrow anything, and only the tinyest fuck about customer pain so long as the checks clear
- zozbot234 4y ago
  RDF does not depend on XML. You can use JSON-LD or text-based syntax (N3, TURTLE or extensions thereof) and those are preferred in modern applications.

janci 4y ago

Cont.: Because using HTTP verbs and status codes is stupid too: - the API is then tied to single "transport" protocol (it is application layer protocol in ISO/OSI but if you are not building a web browser, your application should reside one layer upwards) - it crosses ISO/OSI layer boundaries (exposes URLs in data, uses status codes for application error reporting, uses HTTP headers for pagination etc.) I think the second issue is vastly underrated. Protocols that cross layer boundaries are source of trouble and require tons of workarounds. Do you remember how FTP does not work well with NATs? It's because it exposes IPs and ports - transport layer concepts on application layer. SIP? The same thing. With true REST you can build only HTTP APIs, no websockets, no CLIs, no native libraries.

derefr 4y ago
> exposes URLs in data That's, uh, the point. Without that, it's not "the web." (And yes, properly-structured APIs are part of "the web" — e.g. the first page of your paginated resource can be on one server, while successive pages are on some other archival server.) This is the whole reason for doing HATEOAS: there's no longer a static assumption that you're working against some specific server with a specific schema structure in place. Rather, your API client is surfing the server, just like you're surfing HN right now. > no websockets Correct in a nominal sense, but not in any sense 99% of developers would care about. Instead of RPC over websockets, do REST. Instead of subscriptions over websockets, do REST against a subscription resource for the control-plane, and then GET a Server-Sent Events stream for the data-plane. Perfectly HATEOAS compliant — nobody ever said resource-representations have to be finite.
- janci 4y ago
  > This is the whole reason for doing HATEOAS. Seems like a premature optimization to me. Building all applications so that they potentially could be distributed over multiple servers. YAGNI.
  - zach_garwood 4y ago
    Hello, this is the internet, have you heard of us?

derefr 4y ago

> but no sane client will go around and request random server-provided urls to discover what is available Compare and contrast: what SQL admin GUI clients do to discover the DBMS schema. They essentially spider it. > Under HATEOAS the client would need to associate the knowledge of resource structure with a particular resource received. A promising identifier for this association would be the resource collection path, i.e. the URL. If the client needs to know the URLs, why have them in the response? The client does not need to know the URL; the client needs to know how to get to the URL. Have you ever written a web scraper, for a site that doesn't really enjoy being scraped, and so uses stuff like CSRF protection "synchronizer tokens"? To do/get anything on such a site, you can't just directly go to the thing; you have to start where a real browser would start, and click links / submit forms like a browser would do, to get there. HATEOAS is the idea that APIs should also work that way: "clicking links" and "submitting forms" from some well-known root resource to get to the API you know about. As with a scraper, it's the "link text" or the "form field names" — the delivered API — that you're assuming to be stable; not the URL structure. > Other problems include creating new resource - how the client is supposed to know the structure of to-be created resource, if there is none yet? The client has nothing to request to discover the resource structure and associations. What do you think HTML forms are, if not descriptions of resource templates? When you GET /foos, why do you think the browser result is a form? It's a description of how to make a foo (and, through the submit attribute, a place to send it to get it made.) Alternately, compare/contrast what Kubernetes does — exposes its resource schemas as documents, living in the same resource-hierarchy as the documents themselves live. > Also hypertext does not map well to JSON. In JSON you can not differenciate between data and metadata (i.e. links to other resources) It's right in the name: in HATEOAS, hypertext is the engine of application state. Hypertext as in, say, HTML. JSON is not hypertext, because it's not text — it's not a markup language like SGML/XML/HTML are. You realize that HTML is machine-readable, right? That you can respond to an XHR with HTML, and then parse it using the browser (or API client's) HTML parsing capabilities, just like you can receive and parse JSON? That there's nothing stopping you from using a <table> to send tabular data, etc.? And that if you do so, then debugging your API becomes as simple as just visiting the same link the API client is visiting, and seeing the data rendered as HTML in your browser?

janci 4y ago

wwweston 4y ago

> no sane client will go around and request random server-provided urls to discover what is available. "Random" isn't what's supposed to happen. You hit a top level endpoint, and then at that point other endpoints are made manifest, and then the UA/client and the user decide together what the next relevant endpoint is. And this is what happens all the time with the most common client (the browser). Seems to have worked more or less for 30 years. As for what semantics the UA/client is capable of exploring and providing assistance with: who knows what's possible with additional heuristics + machine learning techniques? > Also hypertext does not map well to JSON... It maps pretty good to XML... understandably nobody wants to work with XML. I don't understand that, actually. Markup is underrated for data exchange potential these days. JSON is frequently (though not always) somewhat lighter on bandwidth and often briefer to type for the same underlying reasons, but beyond that there's no inherent advantage. It just became the easiest serialization/deserialization story, half out of riding the way that JS won, half out of what it didn't bother to try doing (a lot of the meta/semantics) and so gave devs permission to stop thinking about.

janci 4y ago
> You hit a top level endpoint, and then at that point other endpoints are made manifest, and then the UA/client and the user decide together what the next relevant endpoint is. That's not how APIs are used. APIs consume and provide data. Raw data is unsuitable to be presented to the user. That's why HTML has so many formatting options. Formatting information is completely missing from APIs. > Seems to have worked more or less for 30 years. Yes, worked for good old web. In this sense, true REST is nothing new and even seems backwards. If we try to do REST while keeping data and presentation separate, we will come to something very similar to XML for data + XSLT for formatting. Or XForms. Old ideas all over again. > I don't understand that, actually. Markup is underrated for data exchange potential these days. XML/markup does not map well to basic data types in current programming languages. These work with strings, ints, floats and arrays/dictionaries thereof. Not Nodes, Elements and attributes of unknown/variant data types.
- kortex 4y ago
  > XML/markup does not map well to basic data types in current programming languages. These work with strings, ints, floats and arrays/dictionaries thereof. Not Nodes, Elements and attributes of unknown/variant data types Exactly. Arrays are pretty much the most primitive computer data structure (aside from primitives), and the contortions XML must go through to express them is remarkable. So much ceremony, and it can't do a simple list. XML has this core implicit assumption that everything ought to be an object, and I think this was the ultimate death knell for it. You can add complexity to JSON (e.g. JSON-LD) but you can't take the complexity out of XML.