Fieldsets should be defined per resource path instead of resource type

[mwhite]

This is a significant limitation of the existing spec.

If I do a request to a repo resource and want to get multiple related sets of users for each repo in the same request, say, owner, collaborators, watchers, and/or organization.members, there is no way to have a different sparse fieldset for each set of users.

Fields should be able to be defined as fields[owner]=&fields[organization.members]= instead of fields[user].

[dgeb]

Each resource can appear only once in a document, even if it is referenced by multiple relationships. That's the rationale for specifying fieldsets by type instead of path.

[mwhite]

I see, thanks. Have you considered allowing the option to return full related documents inline for each related set in addition to the current option to return them all at the top-level and use resource identifier objects in order to support this use case?

Top-level storage with identifiers potentially reduces query/response size, and makes it easy to ensure that only one client object is created on the client even if there are multiple instances of an object in the JSON, but you can use a library like Backbone-relational that avoids duplicates by identifier by default, or make your custom consumer do that.

Say I want to get all the data for a user page that shows the all the user's details and just their followers' names and location all at once. If user has 10 fields then doing this all in one query currently will return a significant amount of unnecessary data.

[beauby]

@mwhite The problem with your outlined solution is that it does not specify what happens in case of cycles in your data graph.

[mwhite]

True, that would result in unnecessary output duplication for cycles in cases like user.followers.followers.followers. I guess allowing nested related documents is orthogonal to returning different fields for different paths to the same type.

The request format fields[owner]=&fields[organization.members]= could be supported with no changes to the existing response format, with the fields returned for each top-level object being the union of the fields for each path at which that object occurs.

[ethanresnick]

The idea of a query parameter that restricts fields by relationship path, rather than by type, has come up a few times, and I think it's something we're generally sympathetic to as a possible extension. (If the same resource appeared at multiple paths, its fields would be the union of all the path-based fieldsets applied to it, as @mwhite suggested.) For backwards compatibility, we'd probably have to add a new query parameter to support this, but it wouldn't be hard.

[maurei]

In your examples you haven't specified what the field selection of the main resource of the request would look like. There is no way to define this using a path because it is the "root". Would we just use a fields=name without square brackets?

i.e. repositories?fields=name&fields[owner]=last-name