FAQ page

[steveklabnik]

Lots of people asking questions on a few topics:

1. Caching
2. Pagination
3. versioning

We also need to address other specs that we work with; it's not immediately obvious to people that pagination is outside of this spec, since you'd use the standard relations or just define your own.

[steveklabnik]

Oh, and 'why not HAL' https://news.ycombinator.com/item?id=5654212

and comparisons to other major types.

[SphtKr]

Ok, looking forward to the FAQ...but I was thinking about making an issue for pagination, and don't understand this:

it's not immediately obvious to people that pagination is outside of this spec, since you'd use the standard relations or just define your own.

If that's the case, should jsonapi.org remove the references to pagination having a place in the meta reserved key?

[steveklabnik]

It should be in the FAQ rather than the spec directly, yes.
—
Sent from Mailbox for iPhone

On Mon, May 6, 2013 at 5:50 AM, SphtKr notifications@github.com wrote:

Ok, looking forward to the FAQ...but I was thinking about making an issue for pagination, and don't understand this:

it's not immediately obvious to people that pagination is outside of this spec, since you'd use the standard relations or just define your own.

If that's the case, should jsonapi.org remove the references to pagination having a place in the meta reserved key?

Reply to this email directly or view it on GitHub:
#1 (comment)

[luisobo]

I didn't want to create yet another issue for this so I'll put it here:

@wycats discarded HAL because:

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.

I like the idea of flattening the object graph. It make sense for top level entities like author but I don't think it will always make sense in every case: what about relationships of composition, where one entity owns the lifecycle of the entities on the other side of such relationship?. Examples: "Post and Comments" and the textbook example "Order and OrderItems". Both Comments and OrderItems don't make sense without their respective parent entities and I don't think it would make sense to list these entities as top level entities in the document. Also, I would consider the duplication of these entities a smell because they should be encapsulated by their parent entity.

Now, iff this point is considered, this would be my suggestion to achieve it (which may be a big change):

• Instead of having a links attribute, list the relationships like any other member of an object. That member can contain a link (which can be seen as a proxy to the nested document) or the nested document itself:

Instead of

{ "id":"123",
  "title": "foo",
  "body": "bar",
  "links": {
    "comments": "http://api.example.com/post/123/comments",
    "author": "http://api.example.com/people/22"
  }
}

I'd do:

{ "id":"123",
  "title": "foo",
  "body": "bar",
  "comments": {
    "href": "http://api.example.com/post/123/comments"
    // using an object is more extensible (profiles?) because we can fit more info here if needed
  },
  "author": {
    "href": "http://api.example.com/people/22"
  }
}

• Allow relationships to be:
  • present (the nested document) (next example with comments)
  • a link to a remote document (above)
  • a link to another resource in the same document (next example with author)

{ 
"posts":[{
  "id":"123",
  "title": "foo",
  "body": "bar",
  "comments": [{ // comments are included
    "id":"333",
    "message":"laame"
   },{
    "id":"334",
    "message":"I disagree"
   }],
  "author": {
    "href": "http://api.example.com/people/888" // or any other way of pointing to the current document.
  }
}],
"people":[{
  "id":"888",
  "name":"John"
}]
}

The example is incomplete to avoid making this comment even longer.

Thoughts?

[brixen]

I started a FAQ page http://jsonapi.org/faq/. My plan is to go through all the tickets and try to list the questions and answers. Of course, PRs are a option if anyone wants to help out with this. :)

[jezstephens]

+1 for contrasting JSON API with JSON-LD in the FAQ. Especially important with JSON-LD now a W3C Proposed Recommendation.

[steveklabnik]

http://jsonapi.org/faq/