Reading across collections (#164)

* Import Google AIP

* De-Google

* Move proto-specific guidance to a tab.

* Improve phrasing

aep/general/0159/aep.md.j2

@@ -1,5 +1,76 @@
 # Reading across collections
 
-**Note:** This AEP has not yet been adopted. See
-[this GitHub issue](https://github.com/aep-dev/aep.dev/issues/13) for more
-information.
+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`](./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]).
+
+**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 [unreachable resources].
+
+{% tab proto %}
+
+- 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.
+
+{% endtabs %}
+
+### 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`](./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.
+
+## Further reading
+
+- For partial failures due to unreachable resources, see [unreachable
+  resources].
+
+<!-- prettier-ignore-start -->
+
+[unreachable resources]: ./unreachable-resources
+
+<!-- prettier-ignore-end -->

aep/general/0159/aep.yaml

@@ -1,7 +1,7 @@
 ---
 id: 159
-state: reviewing
+state: approved
 slug: reading-across-collections
-created: 2023-01-22
+created: 2024-04-10
 placement:
   category: resources