Nested collections control

[jbjonesjr]

When retrieving items that have a To-Many relationship, it would be nice to have an option that can control the specific hydration of these items to help contain the cost of unnecessary data access.

There are times where a full hydrated resource will be needed and used, and others where that endpoint just makes the most sense, but the actual data is irrelevant. Supporting the ability to reduce these requests is helpful in controlling processing cost.

[jbjonesjr]

A client MAY request that an endpoint return only specific fields in the response by including a fields query parameter.

kind-of, maybe covered by partial resources?

[treyau21]

yes @jbjonesjr ... the partial resources section is the equiv of field limiting operation (so that an integrating app can pair down the data being returned)... granted that's mostly for limiting the fields of the root resource. In the current design, the To-Many relationships still show as a nested representation with an href for that full list (if needed)... granted it requires a subsequent request. That work for what you are thinking? Are the docs clear on that point... or need more meat/examples?

[jbjonesjr]

opps, looking at this again, I was probably speaking of detailed representation, rather than nested collections that seem to be dehydrated by default.

In the example:

...
    "coverArt": "https://ia800500.us.archive.org/2/items/mbid-6282e607-18b3-39c2-822b-b8d7bc00c343/mbid-6282e607-18b3-39c2-822b-b8d7bc00c343-1132379641_thumb500.jpg",
    "releasedAt": "1981-11-23",
    "artist": {
      "id": "247",
      "href": "/artists/247",
      "name": "AC/DC"
    },
    "songs": {
      "href": "/albums/1/songs",
      "totalCount": 10
    }
...

artist could get quite bulky depending on the data schema. Being able to not send that data across the wire would save it response size, and potential expensive data joins and object implementations.

[killerbgt]

@jbjonesjr, when including a To-One relationship in the detailed representation of a resource, it should only be included using its summary representation which is a scaled down version of the resource containing the most commonly used attributes. This allows common attributes of related resources to be fetched along with the parent resource with a slightly larger payload. Field Limiting aka Partial Resources can be used to completely remove attributes (including related resources) from the payload when they are not needed.

[jbjonesjr]

Thinking about this from a relational DB perspective, when the main object/data model has the Foreign Key to the other object, it seems a shame to force hydration (or removal completely).

This may be beyond the scope of this document, which is fine, but in previous API creation I ended up with many permutations of the same "object", one with To-One relationships in full, one with them in summary, and one with them removed. Being able to control these permutations with configuration options definitely is better than the alternative of many different endpoints.

Just my 2 cents.