Compund documents / sideloading

[roynasser]

I think we roughly spoke abt something similar in #294 but that was a while ago and perhaps it was a slightly different thing...

Has anyone accomplished compound exposure, or "sideloading"? Similar to whats discussed here: json-api/json-api#5

Basically lets say I have an API endpoint which returns:

GET /Users
Users:{
    UserName: 'abc',
    LocationID: 1
}

The idea would be something like GET /Users?loadrelated=locations

Users:{
    UserName: 'abc',
    LocationID: 1
},
Locations:{
    LocationID: 1,
    Location: 'new york'
}

as a rough example... This is pretty easy to spot on 1-1 relationships... a bit harder on 1-many and even worse on many-many... Pagination also comes to mind as a problem... What you paginate the main dataset, do you include only the active records of the "current page" for the included items? (i.e. if I am returning only first 5 users, do I return locations for these 5 users, or all?)

What if the number of "locations" (included resource) is too large? How do I paginate those?

I wonder if there are any real world case uses for this and what recommendations might be?

I'm also interested whether bringing things "inside" the record would be useful in some cases? such as:

Users:{
UserName: 'abc',
LocationID: 1
  Locations:{
     LocationID: 1,
     Location: 'new york'
  }
}  

this may generate duplicity in some cases though, but could be useful in other cases where the included things are "hierarchical... such as a detail view for example...

Comments?