feat: AIP-159 – Reading across collections

aip/general/0159/aip.md

@@ -0,0 +1,63 @@
+# 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`][aip-132] operation:
+
+```
+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 operation **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 operation **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`][aip-131] operation 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 operation **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.

aip/general/0159/aip.yaml

@@ -0,0 +1,7 @@
+---
+id: 159
+state: approved
+created: 2019-07-26
+placement:
+  category: design-patterns
+  order: 70