search

tobyzerner / json-api-php

JSON-API (http://jsonapi.org) responses in PHP.
MIT License
436 stars 79 forks source link

Should sparse fieldsets and includes be specified on the document rather than the primary element? #111

Closed tobyzerner closed 7 years ago

tobyzerner commented 7 years ago

Since sparse fieldsets and includes are a global concept, ie, they are specified once in the URL and have an effect on all resources in the document:

GET /articles/1?fields[comments]=body,author&include=comments.author

Does it make sense to be specifying them on Resources/Collections, rather than on the Document itself? eg,

$collection = new Collection($posts, new PostSerializer);

$document = new Document($collection);
$document->setInclude(['comments.author']);
$document->setFields(['comments' => ['body', 'author']]);
tobyzerner commented 7 years ago

Thinking about how this would work in the code, at most it would just be an alternative way of specifying the includes/sparse fieldsets. Under the hood, the Document would simply pass these assignments on to the root Element.

Do people see any value in adding this API?

tobyzerner commented 7 years ago

And some further thought leads me to realize that the Document itself has nothing to do with includes and fields — these are indeed directives for the top-level data, so it absolutely makes sense to be setting them on the root Element.

I see no reason to increase the API surface area here.