3 ms·

The results are intuitive and in favor of GraphQL, especially as query complexity increases. GraphQL makes loads of sense for modern javascript thick clients:

The results are intuitive and in favor of GraphQL, especially as query complexity increases. GraphQL makes loads of sense for modern javascript thick clients: The front end developer is going to want the same thing that a back end developer has: an expressive, general query language. And the API developer should want to give it to them so they aren't dragging their API around all over the place as fiddly UI & application logic changes are made[1]. I'm glad to see javascript client-server apps heading this direction, and leaving REST/HATEOAS to hypertext-oriented approaches[2]. REST sans a hypertext was always a mistake. [1] - https://www.infoq.com/articles/no-more-mvc-frameworks/ https://www.infoq.com/articles/no-more-mvc-frameworks/ [2] - https://htmx.org https://htmx.org

djlewald 6y ago
I am a fan of GraphQL, but what evidence do you have for "REST sans a hypertext was always a mistake"?
- recursivedoubts 6y ago
  REST requires a uniform interface. Hypertext (or media) is that uniform interface. JSON isn't a hypertext. Therefore JSON isn't an appropriate transport for a REST-ful API. I understand that 99% of the internet disagrees with me.
  - t-writescode 6y ago
    Could you define your terms? Especially: * uniform interface * hypertext And even more especially how JSON does not meet the requirements?
    - recursivedoubts 6y ago
      Uniform interface: https://en.wikipedia.org/wiki/Representational_state_transfer#Uniform_interface https://en.wikipedia.org/wiki/Representational_state_transfe... Hypertext: https://en.wikipedia.org/wiki/Hypertext https://en.wikipedia.org/wiki/Hypertext JSON is obviously not a native hypertext, any more than plain text or CSV is. You can, of course, embed URLs in it (or any other format) and call it a hypertext. That's usually pointless, as the links will be consumed by code (rather than a human, in the canonical HTML->browser interaction) so if the URLs aren't simply ignored, they will be dealt with generically. I wrote about this in HATEOAS is for humans: https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.h...
      - t-writescode 6y ago
        Curious to me is that it seems you argue that XML is a valid hypertext; but, isn't it possible to implement most any valid xml document as a json document, even considering attributes? And, have you seen Github's API implementation? They have the links and self-referential details in their particular json schemas that you seem to imply are necessary and unique for that. If the argument is that json can't be rendered, isn't it arguable that xml equally has that problem, we just have a program with a common syntax reader format that renders pages equivalently, and something equivalent could be written for a particular json schema?
        recursivedoubts 6y ago
        I do not think that XML is a hypertext. So I agree with you. HTML is a hypertext. Yes, Github probably has one of the most as-REST-like-as-possible JSON apis, and it's mostly wasted effort. It would be just as usable, as an API, without all that stuff, since it is consumed by code, not a browser/human.
        t-writescode 6y ago
        What does HTML have that XML doesn't have? Isn't XML a superset of HTML?
        recursivedoubts 6y ago
        It has a hypermedia spec: https://www.w3.org/TR/html4/ https://www.w3.org/TR/html4/ And a bunch of things called "browsers" that implement that spec. More or less. I mean, come to that, aren't XML and HTML both just text? Isn't text, then, a hypertext? One can embed URLs in text, after all...
        t-writescode 6y ago
        Does this mean that your argument that json can't be a hypertext is because it doesn't already have a universal hypermedia spec?
clusterhacks 6y ago
I designed a REST API with a "well-documented" HATEOAS representation (collection+json). The primary requirement was to ensure there was no caller-side language dependency because we had multiple teams that would be calling the API and those teams might use the command line, Python, Ruby, Javascript, etc clients to consume the API results. API adoption was low in the end - teams in the end wanted libraries rather than a well-defined representation with embedded hyperlinks. Every consumer I heard about simply parsed the JSON bits they wanted from responses and hard-coded URL links in their client apps. I enjoyed the design and writing of the app - I used Clojure and the liberator library. Probably a wasted effort of engineering in the end. Totally fun project to implement though.
- recursivedoubts 6y ago
  > Every consumer I heard about simply parsed the JSON bits they wanted from responses and hard-coded URL links in their client apps Exactly. HATEOAS is for humans: https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.h...
  - ClumsyPilot 6y ago
    So far I have not experienced HATEOAS deliver value over a wiki with good documentation - that seems like better effort.
    - dragonwriter 6y ago
      > I have never seen how does HATEOAS deliver benefit over a wiki with good documentation - that seems like better effort. Have you used a web browser? Do you see how it handles known content types from a new website that you haven't previously visited seamlessly without you reading docs and telling it what to do with it? That is exactly HATEOAS. In general, understanding REST is often easiest if you think about what browsers do, since REST is the key principal underlying the design of HTTP/1.1 and was largely a rationalization of the evolved behavior of the web per-HTTP/1.1.

djlewald 6y ago

I am a fan of GraphQL, but what evidence do you have for "REST sans a hypertext was always a mistake"?

recursivedoubts 6y ago
REST requires a uniform interface. Hypertext (or media) is that uniform interface. JSON isn't a hypertext. Therefore JSON isn't an appropriate transport for a REST-ful API. I understand that 99% of the internet disagrees with me.
- t-writescode 6y ago
  Could you define your terms? Especially: * uniform interface * hypertext And even more especially how JSON does not meet the requirements?
  - recursivedoubts 6y ago
    Uniform interface: https://en.wikipedia.org/wiki/Representational_state_transfer#Uniform_interface https://en.wikipedia.org/wiki/Representational_state_transfe... Hypertext: https://en.wikipedia.org/wiki/Hypertext https://en.wikipedia.org/wiki/Hypertext JSON is obviously not a native hypertext, any more than plain text or CSV is. You can, of course, embed URLs in it (or any other format) and call it a hypertext. That's usually pointless, as the links will be consumed by code (rather than a human, in the canonical HTML->browser interaction) so if the URLs aren't simply ignored, they will be dealt with generically. I wrote about this in HATEOAS is for humans: https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.h...
    - t-writescode 6y ago
      Curious to me is that it seems you argue that XML is a valid hypertext; but, isn't it possible to implement most any valid xml document as a json document, even considering attributes? And, have you seen Github's API implementation? They have the links and self-referential details in their particular json schemas that you seem to imply are necessary and unique for that. If the argument is that json can't be rendered, isn't it arguable that xml equally has that problem, we just have a program with a common syntax reader format that renders pages equivalently, and something equivalent could be written for a particular json schema?
      - recursivedoubts 6y ago
        I do not think that XML is a hypertext. So I agree with you. HTML is a hypertext. Yes, Github probably has one of the most as-REST-like-as-possible JSON apis, and it's mostly wasted effort. It would be just as usable, as an API, without all that stuff, since it is consumed by code, not a browser/human.
        t-writescode 6y ago
        What does HTML have that XML doesn't have? Isn't XML a superset of HTML?
        recursivedoubts 6y ago
        It has a hypermedia spec: https://www.w3.org/TR/html4/ https://www.w3.org/TR/html4/ And a bunch of things called "browsers" that implement that spec. More or less. I mean, come to that, aren't XML and HTML both just text? Isn't text, then, a hypertext? One can embed URLs in text, after all...
        t-writescode 6y ago
        Does this mean that your argument that json can't be a hypertext is because it doesn't already have a universal hypermedia spec?

clusterhacks 6y ago

I designed a REST API with a "well-documented" HATEOAS representation (collection+json). The primary requirement was to ensure there was no caller-side language dependency because we had multiple teams that would be calling the API and those teams might use the command line, Python, Ruby, Javascript, etc clients to consume the API results. API adoption was low in the end - teams in the end wanted libraries rather than a well-defined representation with embedded hyperlinks. Every consumer I heard about simply parsed the JSON bits they wanted from responses and hard-coded URL links in their client apps. I enjoyed the design and writing of the app - I used Clojure and the liberator library. Probably a wasted effort of engineering in the end. Totally fun project to implement though.

recursivedoubts 6y ago
> Every consumer I heard about simply parsed the JSON bits they wanted from responses and hard-coded URL links in their client apps Exactly. HATEOAS is for humans: https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.h...
- ClumsyPilot 6y ago
  So far I have not experienced HATEOAS deliver value over a wiki with good documentation - that seems like better effort.
  - dragonwriter 6y ago
    > I have never seen how does HATEOAS deliver benefit over a wiki with good documentation - that seems like better effort. Have you used a web browser? Do you see how it handles known content types from a new website that you haven't previously visited seamlessly without you reading docs and telling it what to do with it? That is exactly HATEOAS. In general, understanding REST is often easiest if you think about what browsers do, since REST is the key principal underlying the design of HTTP/1.1 and was largely a rationalization of the evolved behavior of the web per-HTTP/1.1.