Reading across collections
Sometimes, it is useful for a user to be able to retrieve resources across multiple collections, or retrieve a single resource without needing to know what collection it is in.
Guidance
APIs may support reading resources across multiple collections by allowing
users to specify a -
(the hyphen or dash character) as a wildcard character
in a standard List
method:
- The method must explicitly document that this behavior is supported.
- The resources provided in the response must use the canonical name of the
resource, with the actual parent collection identifiers (instead of
-
). - Services may support reading across collections on
List
requests regardless of whether the identifiers of the child resources are guaranteed to be unique. However, services must not support reading across collections onGet
requests if the child resources might have a collision. - Cross-parent requests should not support
order_by
. If they do, the field must document that it is best effort. This is because cross-parent requests introduce ambiguity around ordering, especially if there is difficulty reaching a parent (see unreachable resources).
-
The URI pattern in the
google.api.http
annotation must still be specified with*
and permit the collection to be specified; a URI pattern must not hard-code the-
character.
Note: OAS guidance is yet to be written.
Unique resource lookup
Sometimes, a resource within a sub-collection has an identifier that is unique
across parent collections. In this case, it may be useful to allow a
Get
method to retrieve that resource without knowing which parent
collection contains it. In such cases, APIs may allow users to specify the
wildcard collection ID -
(the hyphen or dash character) to represent any
parent collection:
- The URI pattern should still be specified with a variable and permit the
collection to be specified; a URI pattern should not hard-code the
-
character. Having a separate route for the wildcard case can lead to ambiguous or undefined routing behavior (unless the variable pattern excludes the string"-"
) - The method must explicitly document that this behavior is supported.
- The resource name in the response must use the canonical name of the
resource, with actual parent collection identifiers (instead of
-
). For example, the request above returns a resource with a name likepublishers/123/books/456
, notpublishers/-/books/456
. - The resource ID must be unique within parent collections.
Reading across collections with different path patterns
Sometimes, a resource may have multiple possible path patterns. This typically happens when a resource, or one of its ancestors, may have more than one possible parent resource (including having no parent).
For example, Book
might have the following path patterns:
publishers/{publisher}/books/{book}
for books with a publisherbooks/{book}
for self-published books
In this case, APIs may allow users to read across all collections of
books by using the --
global wildcard sequence:
GET /v1/--/books
Here, --
is not a wildcard for a resource ID within a specific collection.
Rather, it is a wildcard for the entire path pattern. This allows users to
retrieve a book regardless of its resource ancestry.
This pattern may also be used to search all subcollections of a specific
collection. For example, a Playlist
resource might have the following path
patterns:
games/{game}/users/{user}/playlists/{playlist}
for playlists created by a user within a gamegames/{game}/zones/{zone}/playlists/{playlist}
for playlists specific to a game zone
A client could read across all collections of both zone and user playlists
within game 123
with:
GET /v1/games/123/--/playlists
Further reading
- For partial failures due to unreachable resources, see unreachable resources.