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

31–40 of 140 posts

Re: JSON API

#31

Post by 1qaz2wsx3edc »

wycats wrote: post #22
ryanflorence wrote: post #17

Earlier quoted context omitted.

What if I've selected 5 arbitrary people to unfriend? `PUT /friends/???.json`

OP here. Indeed. And importantly, this API makes it possible to restrict the query to a list of documents that the client doesn't already have from another source. In practice, once you start using compound documents with an identity map, there are many cases where existing documents exist on the client and shouldn't be re-fetched. One really simple example is having a number documents that are related to "people" do…

Yes, the first point is valid, data could be re-fetched.

Compounded documents or unions/nested data should only be avoid. I think strong normalization is a good idea.

In the second case. The flow could be:

GET /posts GET /posts/1/comments GET /posts/1/comments/authors

Comments only need to rel to authors, which can be loaded next. Data-binding for the win.

I'm not against embedded data as an optimization. It's difficult to fit.

Re: JSON API

#32

Post by wycats »

alexkcd wrote: post #29
wycats wrote: post #21

Earlier quoted context omitted.

OOP here. There are a lot of these kinds of decisions that need to be made for an API like this. In general, I went with what we're already doing if there was a toss-up. A big strength of JSON API, imho, is that it's an extraction from a real world system that a number of people are already using in some form. It's important to note that the goal of JSON API is to be consumed by a general-purpose client (like Ember D…

That's a fair point, but using arrays only where ordering matters adds nice semantics that can be used by a general-purpose client. Using a map for related documents makes it explicit that document entries are unique and unordered (it's implicitly assumed to be true in OOP's case). In addition, you'll find that you're using an array at the toplevel only for the primary document when it is a collection, and for nested…

Also a fair point.

The original reason for using Arrays (and something that still carries some weight with me), is that people expected that Arrays be presented in a particular order returned by the server. Indeed, the semantics of a to-many relationship need to be set-like (in order to avoid nasty concurrent modification issues), but people really wanted the ability to return an array and have it "work as expected". In general, the right way to handle position, imho, is to use a `position` attribute and sort on the client. After saying all of that, perhaps this is a good reason to use ID indices, so people don't get the wrong idea.

I'll sleep on it :)

Re: JSON API

#33

Post by akamel »

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/

Re: JSON API

#34

Post by wycats »

mahmoudimus wrote: post #24
coderzach wrote: post #10

Why not use JSON HAL? http://stateless.co/hal_specification.html

I second this, what's the point of not using hal?

There are several reasons I chose not to use HAL:

* HAL embeds child documents recursively, while JSON API flattens the entire graph of objects at the top level. This means that if the same "people" are referenced from different kinds of objects (say, the author of both posts and comments), this format ensures that there is only a single representation of each person document in the payload.

* Similarly, JSON API uses IDs for linkage, which makes it possible to cache documents from compound responses and then limit subsequent requests to only the documents that aren't already present locally. If you're lucky, this can even completely eliminate HTTP requests.

* HAL is a serialization format, but says nothing about how to update documents. JSON API thinks through how to update existing records (leaning on PATCH and JSON Patch), and how those updates interact with compound documents returned from GET requests. It also describes how to create and delete documents, and what 200 and 204 responses from those updates mean.

In short, JSON API is an attempt to formalize similar ad hoc client-server interfaces that use JSON as an interchange format. It is specifically focused around using those APIs with a smart client that knows how to cache documents it has already seen and avoid asking for them again.

It is extracted from a real-world library already used by a number of projects, which has informed both the request/response aspects (absent from HAL) and the interchange format itself.

Re: JSON API

#35

Post by jeffamcgee »

The twitter API originally used pages, but they realized it was a mistake: https://dev.twitter.com/docs/working-with-timelines . The way the facebook API does it is a lot more sane: http://developers.facebook.com/docs/reference/api/pagination... .

I think that you should specify the format for cursor based paging of resource collections. One way to do it would be to require a url to get more results:

    {
      "posts": [...]
      "meta": {
        "next":"/posts/search?q=baseball&after=1234"
      }
    }
Another option would be for it to be a key/value pair that must be added to the url:

    {
      "posts": [...]
      "meta": {
        "next":"after=1234"
      }
    }
Either way, rest clients should treat it as a meaningless string.

Re: JSON API

#36

Post by wycats »

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.

Re: JSON API

#37

Post by mahmoudimus »

wycats wrote: post #28
mahmoudimus wrote: post #25

The PATCH mechanisms seem like RPC to me. Having an operation that is passed in the payload, i.e. "replace", is awkward. Why can't you just PATCH a resource? PATCH /resource { "src": "newvalue.png" }

The `PATCH` mechanism is an HTTP verb (RFC 5789: http://tools.ietf.org/html/rfc5789 ) using a standard patching mechanism (RFC 6902: http://tools.ietf.org/html/rfc6902 ). Both are RFCs that seemed like good foundations to build on.

Ah, I hadn't heard of RFC6902. I'll give it a read.

I'm still of the opinion that it might be overkill to use only replace from that RFC when you can just PATCH the actual field to change.

Is there some bit of wisdom or experience that I'm missing?

Re: JSON API

#38

Post by mahmoudimus »

wycats wrote: post #34
mahmoudimus wrote: post #24

Earlier quoted context omitted.

I second this, what's the point of not using hal?

There are several reasons I chose not to use HAL: * HAL embeds child documents recursively, while JSON API flattens the entire graph of objects at the top level. This means that if the same "people" are referenced from different kinds of objects (say, the author of both posts and comments), this format ensures that there is only a single representation of each person document in the payload. * Similarly, JSON API use…

This is a reasonable response.

Re: JSON API

#39

Post by alexkcd »

wycats wrote: post #32
alexkcd wrote: post #29

Earlier quoted context omitted.

That's a fair point, but using arrays only where ordering matters adds nice semantics that can be used by a general-purpose client. Using a map for related documents makes it explicit that document entries are unique and unordered (it's implicitly assumed to be true in OOP's case). In addition, you'll find that you're using an array at the toplevel only for the primary document when it is a collection, and for nested…

Also a fair point. The original reason for using Arrays (and something that still carries some weight with me), is that people expected that Arrays be presented in a particular order returned by the server. Indeed, the semantics of a to-many relationship need to be set-like (in order to avoid nasty concurrent modification issues), but people really wanted the ability to return an array and have it "work as expected".…

I'm not saying you shouldn't use arrays altogether, just that you shouldn't use them when you have uniqueness & no order.

For example, consider the posts.comments.users relationship. Here "posts" is the primary document (and let's say a collection), "comments" and "users" are related documents. The same user may have commented in multiple posts within a single response, so which `position` attribute would you use in the related "users" document? The answer is you don't, you can't, because the user appears in different positions in different posts. The order of comments is defined by the "post" document's "comments" array. Each comment document contains a user id. You look up the user from the unique "users" map by that id. There is no order that makes sense for related documents, since by nature of being related documents their entries may appear in different places/positions in the parent document, where they are already referred to from ordered collections (e.g. arrays of ids) or singular fields.

Hope that clears it all up :)

Re: JSON API

#40

Post by wycats »

mahmoudimus wrote: post #37
wycats wrote: post #28

Earlier quoted context omitted.

The `PATCH` mechanism is an HTTP verb (RFC 5789: http://tools.ietf.org/html/rfc5789 ) using a standard patching mechanism (RFC 6902: http://tools.ietf.org/html/rfc6902 ). Both are RFCs that seemed like good foundations to build on.

Ah, I hadn't heard of RFC6902. I'll give it a read. I'm still of the opinion that it might be overkill to use only replace from that RFC when you can just PATCH the actual field to change. Is there some bit of wisdom or experience that I'm missing?

The main reason was to unify patches to attributes with patches to relationships, which do require richer semantics.

It also makes it really easy to add a compound PATCH (updates to posts/1/title, posts/1/rels/author, posts/2/body, etc. all at the same time) in a single format. Once I bought into JSON Patch for the rest of this stuff, I figured I may as well use it for attributes :)

Post reply on HN