Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

JSON API

jsonapi.org

Post reply on HN
Print view View original

61–70 of 140 posts

Re: JSON API

#61

Post by wycats »

almost wrote: post #58

I think it's great that we're talking about standardising how we build RESTful JSON APIS. However I don't think this has got it quite right yet. What's the reason for the top level rel? It seems like it's just there to stop the urls from being repeated and to save space, but isn't that what gzip is for? Why complicate the data format and require all that extra logic and gzip would remove most of the redundancy before…

> What's the reason for the top level rel? It seems like it's just there to stop the urls from being repeated and to save space, but isn't that what gzip is for?

It also makes it possible to cache things locally indexed on their IDs, and to form URLs that make requests for just the precise documents that aren't available locally. In order to achieve this, it's necessary to have both (1) IDs, and (2) a way to convert a list of IDs into a single request for all of the documents at once.

> Also the name is a bit of an annoying land grab

HAL is "The Hypertext Application Language". In general, people tend to be using generic names for these things, so I chose an available, generic name.

> Lastly, it really seems based on a rails active record style data store, it's assuming ids are the most important thing and that links are all relations that point to other objects within the system

I reviewed a large number of server-side solutions (Firebase, Parse, CouchDB, Django, Rails) and they all had the concept of an ID for the document. As I said above, this ID is useful to keep track of which documents have already been cached locally, and how to formulate a URL that makes a request for just the missing URLs. I don't consider this solution to be particularly tied to ActiveRecord.

Less importantly, it is also more convenient to cache documents on the server using their IDs (or slugs, or whatever the storage wants to use), and allow a top-level configuration to define how to generate URLs. This allows server-side solutions to serialize and cache documents without having to be plugged into the router architecture, but enforces a URL-centric view once the HTTP response is built.

Re: JSON API

#62

Post by ch0wn »

I read a lot of RFCs and drafts for media types lately and what strikes me reading this spec is the very liberal use of MUST which seems to me like an unnecessary violation of the robustness principle, that Jon Postel introduced first in RFC761 (TCP). Mike Amundsen describes in his book 'Building Hypermedia APIs […]':

    Media type designers should keep Postel in mind. Designers can make
    supporting the Robustness Principle easier for implementor by keeping the
    number of MUST elements in the compliance profile to a minimum. The fewer
    MUST elements implementors need to support, the more likely it is that they
    will be able to craft compliant representations using that media type.

Re: JSON API

#63

Post by sandstrom »

wycats wrote: post #36
akamel wrote: post #33

this protocol seems to be a solution for ember; there are already other very similar protocols; why is this called jsonapi.org and not emberjsonapi.org? as noted in other comments, there is JSON HAL; there is also OData (you might not appreciate that it is an ms initiative, but its pretty well established and has many providers) http://www.odata.org/libraries/

JSON HAL is an document format only; it does not formalize a protocol. JSON API is a solution for any "smart" client that is capable of caching documents and intelligently limiting subsequent requests. In general, I believe it will be broadly useful for JavaScript frameworks (and native libraries) that want to abstract the nitty gritty of how a document comes over the wire from its "model" representation.

I think this is an excellent proposal. My only comment would be to clarify, next to the references to Ember, that this isn't exclusive to Ember (it is kind of obvious given the name/domain, but I think it may trip some people up).

Re: JSON API

#64

Post by dualogy »

bitcracker wrote: post #60

It amazes me how programming languages and APIs look more and more like Lisp. Modern languages copy essential features from Lisp, and JSON as one of the most popular JS libs almost look identical to Lisp s-expressions. Someday also more people will realize how useful and effective the equivalence of control structures and data really is. JSON: { "posts": { "id": "1", "title": "Rails is Omakase", "rels": { "author": 9…

Yeah. Well. Also known as "in the end, everything is just an abstract syntax tree". But while a few people will always delight and excel in reading and writing everything as s-expressions, many of us will probably always find either line-breaks or different kinds of braces, brackets and little syntactic doodads make for easier and saner writing and reading -- even if the parser needs to do a bit more work.

No matter what kind of code I'm looking at: "could I express this as s-expressions?" Sure. "Would I want to?" Hell no.

Re: JSON API

#65

Post by cpa »

bitcracker wrote: post #60

It amazes me how programming languages and APIs look more and more like Lisp. Modern languages copy essential features from Lisp, and JSON as one of the most popular JS libs almost look identical to Lisp s-expressions. Someday also more people will realize how useful and effective the equivalence of control structures and data really is. JSON: { "posts": { "id": "1", "title": "Rails is Omakase", "rels": { "author": 9…

I think it's more about the tree data structure than about LISP. LISP just makes the underlying data structure obvious, but as you implied we are far from seeing any LISP-semantics in JS(ON).

Re: JSON API

#66

Post by bitcracker »

dualogy wrote: post #64
bitcracker wrote: post #60

It amazes me how programming languages and APIs look more and more like Lisp. Modern languages copy essential features from Lisp, and JSON as one of the most popular JS libs almost look identical to Lisp s-expressions. Someday also more people will realize how useful and effective the equivalence of control structures and data really is. JSON: { "posts": { "id": "1", "title": "Rails is Omakase", "rels": { "author": 9…

Yeah. Well. Also known as "in the end, everything is just an abstract syntax tree". But while a few people will always delight and excel in reading and writing everything as s-expressions, many of us will probably always find either line-breaks or different kinds of braces, brackets and little syntactic doodads make for easier and saner writing and reading -- even if the parser needs to do a bit more work. No matter…

> "could I express this as s-expressions?" Sure. "Would I want to?" Hell no.

Of course it is possible to implement syntactic sugar in Lisp which supports JSON style expressions. DSLs are common in Lisp, and that actually became a weakness of Lisp (so-called "DSL hell").

The interesting thing about s-expr is that Lisp doesn't need special data conversion tools to handle them. Even control structures are expressed as s-expr, and they can be created and modified dynamically which means that even code can be exchanged at runtime on the fly.

Re: JSON API

#67

Post by almost »

wycats wrote: post #61
almost wrote: post #58

I think it's great that we're talking about standardising how we build RESTful JSON APIS. However I don't think this has got it quite right yet. What's the reason for the top level rel? It seems like it's just there to stop the urls from being repeated and to save space, but isn't that what gzip is for? Why complicate the data format and require all that extra logic and gzip would remove most of the redundancy before…

> What's the reason for the top level rel? It seems like it's just there to stop the urls from being repeated and to save space, but isn't that what gzip is for? It also makes it possible to cache things locally indexed on their IDs, and to form URLs that make requests for just the precise documents that aren't available locally. In order to achieve this, it's necessary to have both (1) IDs, and (2) a way to convert…

The thing is that "JSON API" was not available, it's already in common use to describe APIs that use JSON. "HAL" is totally not the same, it's clearly a name chosen to not conflict with existing terminology.

The proper layer for caching is HTTP, do we really want to end up with duplicated overlapping functionality between the layers? I see you have an application specific need for a certain thing but I don't think it generalises enough.

A few other things I noticed:

- There's no name spaceing of your special properties, they're just mixed up with the domain-specific properties. So I can't have a property of my object named "rel" and worse still you can't ever add features to the spec without breaking backwards compatibility.

- No type information in items, which kind of breaks automatic caching.

- Multiple entities returned for a URL with no indication as to which is the main one represented by that URL and which are just extra associated ones.

Re: JSON API

#68

Post by almost »

steveklabnik wrote: post #57
eranation wrote: post #11

This is great, but I can't seem to be able to find the NoSQL flavored support. Seems great for relational style data models, but (I'm sure I'm missing something) I didn't see support for full nested document models. Did I entirely miss the point?

The implementation detail of "SQL or NoSQL" should not bubble up to your API. The data store you use is totally irrelevant, that's the entire point of encapsulation.

You've just summed up what bothers me about this format.

Re: JSON API

#69

Post by notimetorelax »

bitcracker wrote: post #60

It amazes me how programming languages and APIs look more and more like Lisp. Modern languages copy essential features from Lisp, and JSON as one of the most popular JS libs almost look identical to Lisp s-expressions. Someday also more people will realize how useful and effective the equivalence of control structures and data really is. JSON: { "posts": { "id": "1", "title": "Rails is Omakase", "rels": { "author": 9…

Or in Clojure:

  { "posts" { "id" "1", "title" "Rails is Omakase", "rels" { "author" 9, "comments" [ 5, 12, 17, 20 ] } } }
Commas are unnecessary, I kept them for clarity.

Re: JSON API

#70

Post by arianvanp »

bitcracker wrote: post #66
dualogy wrote: post #64

Earlier quoted context omitted.

Yeah. Well. Also known as "in the end, everything is just an abstract syntax tree". But while a few people will always delight and excel in reading and writing everything as s-expressions, many of us will probably always find either line-breaks or different kinds of braces, brackets and little syntactic doodads make for easier and saner writing and reading -- even if the parser needs to do a bit more work. No matter…

> "could I express this as s-expressions?" Sure. "Would I want to?" Hell no. Of course it is possible to implement syntactic sugar in Lisp which supports JSON style expressions. DSLs are common in Lisp, and that actually became a weakness of Lisp (so-called "DSL hell"). The interesting thing about s-expr is that Lisp doesn't need special data conversion tools to handle them. Even control structures are expressed as s…

This is one of the most attractive things of lisp. The fact that the language has no notion of compiletime, evaltime and runtime. The user just doesnt have to care abouut it. Very powerful
Post reply on HN