What top level "included" should be?

1

Hi,

I am bit confused reading this,

A document MAY contain any of these top-level members:

jsonapi: an object describing the server’s implementation
links: a links object related to the primary data.
included: an array of resource objects that are related to the primary data and/or each other (“included resources”).

Say, if I have an instance “org” with the following relationships,

 org (dir)
   File{'name='o1.txt', size=1000}
   File{l'name='o2.txt', size=5000}
   departments (dir)
     File{l'name='d1.txt', size=200}
     File{l'name='d2.txt', size=300}
     users (dir)
       File{'null'name='u1.txt', size=3000}
       File{'null'name='u2.txt', size=5000}
   utils (dir)

i.e. “org” has 2 dirs and 2 files at the top level.

My question is should I include “users” instance in “included”?

I am unsure about this because “users” is not directly related to the top-object but it is related to the included “departments”. At the same time, the specs also mentioned to include objects related to “included resources”.

If I do include “users” in this case, which is unrelated to the top object, then I have to include everything and would run into troubles if I have a huge object graph. Alternatively, should I set a limit somewhere during serialization? Thanks.

2

You’re referring to compound documents, where related resources are not embedded in the main document, but added to the included list so that they are returned, but there are no duplicates. See this section for more info: http://jsonapi.org/format/#document-compound-documents

1 Like
3

In other words, in your example Org is the main resource (this would be the data hash), then each relationship (File, Departments) would be part of the data.relationships hash, but only their IDs would be in the relationships hash. Each of those relationships would be part of the included array.

1 Like