4 ms·

You should render the output as actual JSONAPI (http://jsonapi.org http://jsonapi.org): { "links": { "self": "...", "prev": "...",

You should render the output as actual JSONAPI (http://jsonapi.org http://jsonapi.org): { "links": { "self": "...", "prev": "...", "next": "..." }, "data": [], "included": [] } So that we can discover the API beyond the form. Use http://www.iana.org/assignments/link-relations/link-relations.xhtml http://www.iana.org/assignments/link-relations/link-relation... as the starting point for link relations ideas.

wyldfire 11y ago
I was pretty quick to knee jerk ask myself "Why is this any better than any other schema?" (I was not convinced that "API discovery" was, by itself, a good enough case). Then I read the very practical first sentence of the jsonapi page: "If you've ever argued with your team about the way your JSON responses should be formatted, JSON API can be your anti-bikeshedding tool." That alone is probably huge. May not mean much for individual projects, but it's good enough for me to bookmark for the future.
- despinozist 11y ago
  Ya I was like why all teh downvotes y'all? Then I realized I had no actual link ("http://" http://") in my initial post. I tend to assume all have read exactly what I have read. JSONAPI has huge implications for distributed systems architecture.
- fishnchips 11y ago
  Can't help but think of https://xkcd.com/927/ https://xkcd.com/927/ ;) Not sure if standards like this can prevent bikeshedding. You can always bikeshed about the need to stick to any particular standard. One counterexample to what I'm saying may be one standard Go language formatting with gofmt but that was introduced very early on and became a part of the culture. Too late for that with JSON APIs.
jamiesonbecker 11y ago
> You should [...] At least there's no namespacing or DTD's! JSON plus a loose adherence to REST won out over SOAP/XML-RPC/WSDL/etc because of its simplicity. Services discovery seems to be a solution in search of a problem. Even the simple idea of embedded links, with apologies to Dr. Fielding, seem to be a less critical component of REST than was initially believed, since very few modern REST API's actually provide them.
- dragonwriter 11y ago
  Very few modern "REST" APIs have even a remote resemblance to the REST architecture described by Fielding, it's mostly just RPC over HTML with data in an specialized subset of JSON or XML that is specified per endpoint out-of-band rather than indicated by media type. I really wish people would stop calling it REST, since that Rob's the meaning from the term.
  - jamiesonbecker 11y ago
    To some point, I agree! I also used to be a REST purist, but I've become more pragmatic in recent years. Some crucial points that are often preserved even in today's API's that distinguish them from RPC: - Any REST API will have the concept of resources that are acted upon by HTTP verbs (methods), instead of RPC-style calling a method named in the URI. - statelessness (no session state assumed on the server) - use of HTTP status codes - resource path generally indicates hierarchy or at least a specific 'one path to this representation' - broad use of existing HTTP headers for metadata instead of a separate "envelope" in the body as in SOAP - use of common HTTP headers such as Authorization rather than cookies or other carriers of state Many of the other compromises are not always because of ignorances, but in order to be broadly useful in the most common cases. I don't disagree with your point about not calling it REST, because this trend does diverge from Dr. Fielding's dissertation in several important areas (for example, content negotiation, as you point out). That's why I prefer the term "loose REST".
developer2 11y ago
I'd like to point out that this formatting convention is not a widespread standard. "You should" is biased towards making life simpler for a small number of people who have used the format before, while complicating and bloating your API responses - for both the developer(s) and consumers of your API. Consumers are now expected to add a full library to their project to parse/understand the JSON responses. Also, implementation overload for many languages: http://jsonapi.org/implementations/ http://jsonapi.org/implementations/

wyldfire 11y ago

I was pretty quick to knee jerk ask myself "Why is this any better than any other schema?" (I was not convinced that "API discovery" was, by itself, a good enough case). Then I read the very practical first sentence of the jsonapi page: "If you've ever argued with your team about the way your JSON responses should be formatted, JSON API can be your anti-bikeshedding tool." That alone is probably huge. May not mean much for individual projects, but it's good enough for me to bookmark for the future.

despinozist 11y ago
Ya I was like why all teh downvotes y'all? Then I realized I had no actual link ("http://" http://") in my initial post. I tend to assume all have read exactly what I have read. JSONAPI has huge implications for distributed systems architecture.
fishnchips 11y ago
Can't help but think of https://xkcd.com/927/ https://xkcd.com/927/ ;) Not sure if standards like this can prevent bikeshedding. You can always bikeshed about the need to stick to any particular standard. One counterexample to what I'm saying may be one standard Go language formatting with gofmt but that was introduced very early on and became a part of the culture. Too late for that with JSON APIs.

jamiesonbecker 11y ago

> You should [...] At least there's no namespacing or DTD's! JSON plus a loose adherence to REST won out over SOAP/XML-RPC/WSDL/etc because of its simplicity. Services discovery seems to be a solution in search of a problem. Even the simple idea of embedded links, with apologies to Dr. Fielding, seem to be a less critical component of REST than was initially believed, since very few modern REST API's actually provide them.

dragonwriter 11y ago
Very few modern "REST" APIs have even a remote resemblance to the REST architecture described by Fielding, it's mostly just RPC over HTML with data in an specialized subset of JSON or XML that is specified per endpoint out-of-band rather than indicated by media type. I really wish people would stop calling it REST, since that Rob's the meaning from the term.
- jamiesonbecker 11y ago
  To some point, I agree! I also used to be a REST purist, but I've become more pragmatic in recent years. Some crucial points that are often preserved even in today's API's that distinguish them from RPC: - Any REST API will have the concept of resources that are acted upon by HTTP verbs (methods), instead of RPC-style calling a method named in the URI. - statelessness (no session state assumed on the server) - use of HTTP status codes - resource path generally indicates hierarchy or at least a specific 'one path to this representation' - broad use of existing HTTP headers for metadata instead of a separate "envelope" in the body as in SOAP - use of common HTTP headers such as Authorization rather than cookies or other carriers of state Many of the other compromises are not always because of ignorances, but in order to be broadly useful in the most common cases. I don't disagree with your point about not calling it REST, because this trend does diverge from Dr. Fielding's dissertation in several important areas (for example, content negotiation, as you point out). That's why I prefer the term "loose REST".

developer2 11y ago

I'd like to point out that this formatting convention is not a widespread standard. "You should" is biased towards making life simpler for a small number of people who have used the format before, while complicating and bloating your API responses - for both the developer(s) and consumers of your API. Consumers are now expected to add a full library to their project to parse/understand the JSON responses. Also, implementation overload for many languages: http://jsonapi.org/implementations/ http://jsonapi.org/implementations/