AIP-159

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 URI pattern must still be specified with * and permit the collection to be specified; a URI pattern must not hard-code the - character.
  • 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 AIP-217).

Important: If listing across multiple collections introduces the possibility of partial failures due to unreachable parents (such as when listing across locations), the method must indicate this following the guidance in AIP-217.

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://example.googleapis.com/v1/publishers/-/books/{book}
  • The URI pattern must still be specified with * and permit the collection to be specified; a URI pattern must not hard-code the - character.
  • 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.

Further reading

  • For partial failures due to unreachable resources, see AIP-217.

Changelog

  • 2019-08-26: Added a reference to guidance for unreachable resources.
  • 2019-08-01: Changed the examples from "shelves" to "publishers", to present a better example of resource ownership.