Skip to content

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:

GET /v1/publishers/-/books?filter=...
  • 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 on Get 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.

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:

GET https://library.exampleapis.com/v1/publishers/-/books/{book}
  • 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 like publishers/123/books/456, not publishers/-/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 publisher
  • books/{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 game
  • games/{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