5 ms·

I feel like the author has conflated hypertext with html. The REST interface should be self describing, but that can be done in JSON. If you go to Roy Fieldin

I feel like the author has conflated hypertext with html. The REST interface should be self describing, but that can be done in JSON. If you go to Roy Fielding's post... there is a comment where someone asks for clarification, and he responds: > When I say hypertext, I mean the simultaneous presentation of information and controls such that the information becomes the affordance through which the user (or automaton) obtains choices and selects actions. Hypermedia is just an expansion on what text means to include temporal anchors within a media stream; most researchers have dropped the distinction. > Hypertext does not need to be HTML on a browser. Machines can follow links when they understand the data format and relationship types. So, to me, a proper format is something like... id: 1234 url: http://.../1234 http://.../1234 name: foo department: http://.../department/5555 http://.../department/5555 projects: http://.../projects/?user_id=1234 http://.../projects/?user_id=1234 This is hypertext in the sense that I can jump around (even in a browser that renders the urls clickable) to other resources related to this resource.

shadowgovt 4y ago
In practice, this turns out to be a painful way for a client to access the data; instead of a single fetch to get the relevant information, we're now doing multiple fetches and collating the results client-side. For this kind of data access, I'd recommend either a) just denormalizing the field contents if you know what the client needs them for b) supporting GraphQL if you want to support a general-purpose query endpoint
- derefr 4y ago
  REST says nothing about normalization. In fact the opposite — a resource representation in REST is the very same thing as a graph in GraphQL, or a view in SQL: an arbitrary remix of underlying data. REST is meant to be a projected view-model layer for web clients to interact with underlying data through; it's not meant to inform or be strongly bound to the shape of that underlying data.
a3w 4y ago
I found that json-ld, json-hal and other "describe your json" standards were needed to make json human readable-ish. I hate that there are many competing standards and the link syntax feels clumsy. JSON5 for "add comments, allow ES6 features" was perfect for private and in a small team use for a while. No one seems to listen to the JSON inventor, who said he regrets creating a misnomer name and no successor should use the same naming parts, since it neither dependent on or compatible with JavaScript, nor was it only useful for storing and/or describing objects. (I am paraphrasing from my memory on his reasoning on both points.) Open API 3 solved that problem for me, transforming JSON-RPC into a documentented API.
- root_axis 4y ago
  JSON is syntactically valid JavaScript, why do you say it's not compatible with JavaScript?
  - krainboltgreene 4y ago
    Not all JSON is syntactically valid javascript.
    - alexisbear 4y ago
      Since ES2019[1], all JSON is valid JavaScript with U+2028 and U+2029 being accepted as unescaped characters in strings. 1: https://tc39.es/proposal-json-superset/ https://tc39.es/proposal-json-superset/
  - WickyNilliams 4y ago
    JSON is not a strict subset of JS in that `true` is valid JSON, but not a valid JS program. Might be considered a nitpick but in a thread about semantics it's worth noting
  - a3w 4y ago
    Ask Douglas Crockford. I did not find my source on his apprehension of his name. What id did find: He states that he did plan for JSON to be a JavaScript subset, which contradicts his later finding, for which I have only me memory as a source, that JSON is not in some sense JavaScript. More on topic, I did find a source that it was never meant to be human-readable in the sense of usable for documentation, but a machine-communication language, therefore comments were removed from the initial draft to avoid having non-standard meanings put in the freedom comments allow (think pre-process directives etc.).
recursivedoubts 4y ago
No, I haven't. JSON can be used as a hypermedia, and people have tried this, but it hasn't really worked out very much and the industry trend is against it, towards a more RPC-like approach. I'm using HTML as an example to demonstrate the uniform interface constraint of REST, and showing how this particular JSON (and, I claim with confidence, most extent JSON APIs) do not have a uniform interface. Which is fine: the uniform interface hasn't turned out to be as useful when it is consumed by code rather than humans. There are good examples of successful non-HTML hypermedias. One of my favorites is hyperview, a mobile hypermedia: https://hyperview.org/ https://hyperview.org/
- wvenable 4y ago
  I'm old enough to remember WML which was a mobile non-HTML hypermedia standard. I enjoyed using it but it was obvious putting an HTML browser on a phone was always going to win out. Hyperview isn't that interesting because it's a non-standard proprietary technology that isn't really "on the web". So you either have something like that, an actual full-featured HTML browser, or have something consuming a fully defined JSON API. It doesn't feel like there's anything interesting about non-HTML user agents on the web. HTML automatically makes them all irrelevant.
  - recursivedoubts 4y ago
    hyperview is a hypermedia that exposes native mobile features directly within the hypermedia you wouldn't create an internet out of hyperview-apps, rather it is a way for you, a developer of a mobile application, to get the benefits of a hypermedia approach (e.g. versioning becoming much less of an issue, vs. app-store updates) while not giving up on native mobile behavior it is open source, and I think it's one of the most innovative uses of hypermedia I've seen in the last decade: https://github.com/instawork/hyperview https://github.com/instawork/hyperview
    - wvenable 4y ago
      It's an app builder not a hypermedia client. It's a pretty slight semantic difference but when we're talking about REST APIs for 3rd party clients then hyperview isn't really relevant to the discussion.

shadowgovt 4y ago

In practice, this turns out to be a painful way for a client to access the data; instead of a single fetch to get the relevant information, we're now doing multiple fetches and collating the results client-side. For this kind of data access, I'd recommend either a) just denormalizing the field contents if you know what the client needs them for b) supporting GraphQL if you want to support a general-purpose query endpoint

derefr 4y ago
REST says nothing about normalization. In fact the opposite — a resource representation in REST is the very same thing as a graph in GraphQL, or a view in SQL: an arbitrary remix of underlying data. REST is meant to be a projected view-model layer for web clients to interact with underlying data through; it's not meant to inform or be strongly bound to the shape of that underlying data.

a3w 4y ago

I found that json-ld, json-hal and other "describe your json" standards were needed to make json human readable-ish. I hate that there are many competing standards and the link syntax feels clumsy. JSON5 for "add comments, allow ES6 features" was perfect for private and in a small team use for a while. No one seems to listen to the JSON inventor, who said he regrets creating a misnomer name and no successor should use the same naming parts, since it neither dependent on or compatible with JavaScript, nor was it only useful for storing and/or describing objects. (I am paraphrasing from my memory on his reasoning on both points.) Open API 3 solved that problem for me, transforming JSON-RPC into a documentented API.

root_axis 4y ago
JSON is syntactically valid JavaScript, why do you say it's not compatible with JavaScript?
- krainboltgreene 4y ago
  Not all JSON is syntactically valid javascript.
  - alexisbear 4y ago
    Since ES2019[1], all JSON is valid JavaScript with U+2028 and U+2029 being accepted as unescaped characters in strings. 1: https://tc39.es/proposal-json-superset/ https://tc39.es/proposal-json-superset/
- WickyNilliams 4y ago
  JSON is not a strict subset of JS in that `true` is valid JSON, but not a valid JS program. Might be considered a nitpick but in a thread about semantics it's worth noting
- a3w 4y ago
  Ask Douglas Crockford. I did not find my source on his apprehension of his name. What id did find: He states that he did plan for JSON to be a JavaScript subset, which contradicts his later finding, for which I have only me memory as a source, that JSON is not in some sense JavaScript. More on topic, I did find a source that it was never meant to be human-readable in the sense of usable for documentation, but a machine-communication language, therefore comments were removed from the initial draft to avoid having non-standard meanings put in the freedom comments allow (think pre-process directives etc.).

recursivedoubts 4y ago

No, I haven't. JSON can be used as a hypermedia, and people have tried this, but it hasn't really worked out very much and the industry trend is against it, towards a more RPC-like approach. I'm using HTML as an example to demonstrate the uniform interface constraint of REST, and showing how this particular JSON (and, I claim with confidence, most extent JSON APIs) do not have a uniform interface. Which is fine: the uniform interface hasn't turned out to be as useful when it is consumed by code rather than humans. There are good examples of successful non-HTML hypermedias. One of my favorites is hyperview, a mobile hypermedia: https://hyperview.org/ https://hyperview.org/

wvenable 4y ago
I'm old enough to remember WML which was a mobile non-HTML hypermedia standard. I enjoyed using it but it was obvious putting an HTML browser on a phone was always going to win out. Hyperview isn't that interesting because it's a non-standard proprietary technology that isn't really "on the web". So you either have something like that, an actual full-featured HTML browser, or have something consuming a fully defined JSON API. It doesn't feel like there's anything interesting about non-HTML user agents on the web. HTML automatically makes them all irrelevant.
- recursivedoubts 4y ago
  hyperview is a hypermedia that exposes native mobile features directly within the hypermedia you wouldn't create an internet out of hyperview-apps, rather it is a way for you, a developer of a mobile application, to get the benefits of a hypermedia approach (e.g. versioning becoming much less of an issue, vs. app-store updates) while not giving up on native mobile behavior it is open source, and I think it's one of the most innovative uses of hypermedia I've seen in the last decade: https://github.com/instawork/hyperview https://github.com/instawork/hyperview
  - wvenable 4y ago
    It's an app builder not a hypermedia client. It's a pretty slight semantic difference but when we're talking about REST APIs for 3rd party clients then hyperview isn't really relevant to the discussion.