I have a collection of resources, each individual resource contains a lot of data (or data that is expensive to obtain), so by default I would like the collection resource to return only references to individual resources. However, I would also like to give clients a method of obtaining the full details of the individual resources without having to make multiple API calls. My initial approach was for the collection resource to look like this:
"data":[ {"type": "aResource", "id": "dfd", "links":{"self": "http://example.com/resources/dfd"}}, {"type": "aResource", "id": "ghh", "links":{"self": "http://example.com/resources/ghh"}}, {"type": "aResource", "id": "tyt", "links":{"self": "http://example.com/resources/tyt"}}, {"type": "aResource", "id": "klh", "links":{"self": "http://example.com/resources/klh"}}, {"type": "aResource", "id": "uty", "links":{"self": "http://example.com/resources/uty"}} ]
but the “include” parameter operates on related resources, not on links.
The individual resources all have the same relationship to the collection - they’re merely members of it - so I can’t make the collection look like this:
"data":[ {"type": "aResourceCollection", "id": "someid", "relationships": { "member": {"links":{"self": "http://example.com/resources/member"}}, "member": {"links":{"self": "http://example.com/resources/member"}}, "member": {"links":{"self": "http://example.com/resources/member"}}, "member": {"links":{"self": "http://example.com/resources/member"}}, "member": {"links":{"self": "http://example.com/resources/member"}}, } } ]
because there is no way to distinguish the individual resources.
I could make the collection look like this:
"data":[ {"type": "aResource", "id": "dfd", "attributes": {<big_or_expensive_to_obtain}, "links":{"self": "http://example.com/resources/dfd"}}, {"type": "aResource", "id": "ghh", "attributes": {<big_or_expensive_to_obtain}, "links":{"self": "http://example.com/resources/ghh"}}, {"type": "aResource", "id": "tyt", "attributes": {<big_or_expensive_to_obtain}, "links":{"self": "http://example.com/resources/tyt"}}, {"type": "aResource", "id": "klh", "attributes": {<big_or_expensive_to_obtain}, "links":{"self": "http://example.com/resources/klh"}}, {"type": "aResource", "id": "uty", "attributes": {<big_or_expensive_to_obtain}, "links":{"self": "http://example.com/resources/uty"}} ]
and expose it via two URLs, one for the full-fat version, and one that included fields[] to force the API to drop the rest of the data but that feels like an abuse of the fields parameter.
Or I could ask clients to use the HTTP Prefer header to request thin or fat representations but that feels like working round JSON API rather than with it.
What’s the best approach to this problem?