Request for additional guidelines for nested/embedded collections

[danielcrenna]

Currently, the guidelines mention the URL structure for nested collections within a resource:

https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#931-nested-collections-and-properties

GET https://api.contoso.com/v1.0/people/123/addresses

The guidelines also mention that paging semantics should be consistent between the parent and any nested collections.

However, there are some important details missing for ensuring a consistent experience that I'd like clarification on:

• How does the API indicate to a developer that a resource contains a nested collection? In the example above, addresses is out-of-band information. If the original collection query returns addresses data, how is it represented?

For example::

• Similar to @nextLink, @deltaLink, or @added, it could provide a reference merely referring to the JSON path from which to query the nested collection.
• It could be a partial set (but then, this begs the question of how the query URL structure would handle the paging semantics for this, and seems not ideal if the developer doesn't want to pull an arbitrary number of nested records on each query only as a way of indicating they exist)
• It could come via Link relations in a header
• It could come through an OPTIONS call to the parent resource

It seems like the guidelines are leading us to keeping nested collections on their own discrete resource path without the additional complexity of "dot notation" in query semantics to indicate nested paths, or similar, but it's not clear how we're meant to expose the existence of the nested collections themselves.