4 ms·

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?
        recursivedoubts 6y ago
        The language here is getting a little squirrly. "Can't be a hypertext" is too restrictive. "Isn't a hypertext" is how I would say it. JSON as JSON isn't a hypertext in the same way that XML as XML isn't a hypertext. XHTML is a hypertext based on XML. (HTML itself isn't proper XML.) There are hypertext specs based on JSON, such as: https://json-schema.org/draft-04/json-schema-hypermedia.html https://json-schema.org/draft-04/json-schema-hypermedia.html But, without clients that treat the data as a uniform interface, it's all mostly pointless, which is why most JSON APIs stop at Level 2 of the Richardson Maturity Model, and why things like GraphQL are becoming more and more popular. In the original model of the web (which is what Fielding was describing w/ REST) where HTML was being delivered to a browser, the uniform interface works: a browser has no idea what the HTML document means but can render it to a form that the human looking at it can make sense of.

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?
        recursivedoubts 6y ago
        The language here is getting a little squirrly. "Can't be a hypertext" is too restrictive. "Isn't a hypertext" is how I would say it. JSON as JSON isn't a hypertext in the same way that XML as XML isn't a hypertext. XHTML is a hypertext based on XML. (HTML itself isn't proper XML.) There are hypertext specs based on JSON, such as: https://json-schema.org/draft-04/json-schema-hypermedia.html https://json-schema.org/draft-04/json-schema-hypermedia.html But, without clients that treat the data as a uniform interface, it's all mostly pointless, which is why most JSON APIs stop at Level 2 of the Richardson Maturity Model, and why things like GraphQL are becoming more and more popular. In the original model of the web (which is what Fielding was describing w/ REST) where HTML was being delivered to a browser, the uniform interface works: a browser has no idea what the HTML document means but can render it to a form that the human looking at it can make sense of.