Requesting includes about json-api

[hjdivad]

I like this. As with #20, I suggest making it an optional feature.

[lukfugl]

Not a duplicate with #5, since it was closed without change. But from the discussion on that issue, #5 (comment) is a good example of the most common mechanism for this "in the wild" .

[dgeb]

In an API I have under development, I support this by allowing related records to be included with an include param. For instance:

/posts/1?include=comments

I've found that a flat listing is not always sufficient, because we may want to include relationships relative to particular related records. Let's say that you want to include the post, comments and authors of comments (but not authors of the post):

/posts/1?include=comments(authors)

Simarly, if you want to include authors of posts as well:

/posts/1?include=authors,comments(authors)

As I mentioned in #20, I have already centralized and generalized all this logic to work with AMS so that it's transparent to controllers and serializers, and I will gladly share if this approach is chosen for the spec.

[lukfugl]

Hmm, github relabeled the second link in my previous comment, but the second link is to a specific comment in it's discussion. :)

[lukfugl]

Also, related to this, in Canvas' API (https://canvas.instructure.com/doc/api/) we also use the include query parameter to toggle subsets of the resource's non-relational properties.

For example, when listing courses, including include[]=syllabus_body in the query parameters will cause the returned course documents to have a syllabus_body member. This is not a related document (in the current API; maybe it should be), but is a simple string value. However, it can be quite large, so it's advantageous to only include it in the response when explicitly requested.

I'm not holding up Canvas' API as something the needs to be (or even should be) emulated here, but when considering how we want to control conditional side-loading, we should try to keep in mind non-relational use cases.

[lukfugl]

Oh, I see now that @indirect mentions that in #20. I still think the two should be considered in combination...

[GavinJoyce]

A copy of my note from #5 :

---

Here's some examples of how I plan to use conditional side-loading with restpack-serializer. These examples model Artists -> Albums -> Songs rails app source.

Here is a collection of artists:

http://restpack-serializer-sample.herokuapp.com/artists.json

And here are just two:

http://restpack-serializer-sample.herokuapp.com/artists.json?ids=1,2

Let's side-load their albums:

http://restpack-serializer-sample.herokuapp.com/artists.json?ids=1,2&includes=albums

Now we'll side-load albums and songs:

http://restpack-serializer-sample.herokuapp.com/artists.json?ids=1,2&includes=albums,songs

Notice that as there may be a large number of songs (there are 31 in this case), we're only returning the first page here. I plan to add links to additional pages in the meta data, the URLs will take the following form:

http://restpack-serializer-sample.herokuapp.com/songs.json?artist_ids=1,2&page=2

or if we want to include side-loads:

http://restpack-serializer-sample.herokuapp.com/songs.json?artist_ids=1,2&page=2&includes=artists,albums

I plan to implement some of the json-api draft in the coming days so expect the JSON output to become more familiar soon.