feat(124): Resource Associations (#146)

This adds AEP-0124 along with proto and OpenAPI examples.

---------

Co-authored-by: Yusuke Tsutsumi <[email protected]>

Author: rambleraptor

aep/general/0124/aep.md.j2

@@ -1,5 +1,85 @@
 # Resource association
 
-**Note:** This AEP has not yet been adopted. See
-[this GitHub issue](https://github.com/aep-dev/aep.dev/issues/57) for more
-information.
+APIs sometimes have resource relationships that can not be cleanly expressed in
+a hierarchical structure. For example, a resource may have a many-to-one
+relationship with two other resource types instead of just one. Alternatively,
+a resource may have a many-to-many relationship with another resource type.
+
+## Guidance
+
+A resource **must** have at most one canonical parent, and `List` requests
+**must not** require two distinct "parents".
+
+### Multiple many-to-one associations
+
+If a resource has a many-to-one relationship with multiple resource types, it
+**must** choose at most one of them to be the parent. The resource
+**may** be associated with other resources through other fields on the
+resource.
+
+{% tab proto %}
+
+{% sample 'multiple_many_to_one.proto', 'message Book' %}
+
+{% tab oas %}
+
+{% sample 'multiple_many_to_one.oas.yaml', 'Book' %}
+
+{% endtabs %}
+
+When listing resources with multiple associations in this way, the RPC **must**
+treat the `string parent` field as required as discussed in [list](/list), and
+**must not** add additional required arguments. The RPC **should** include a
+`string filter` field that allows users to filter by other resource
+associations as discussed in [filtering](/filtering).
+
+**Note:** Resource reference fields **must** accept the [resource path](/resource-path) of the referenced resource.
+
+### Many-to-many associations
+
+Many-to-many associations are less common in APIs than they are in relational
+databases, in part because they are more difficult to model and present over
+network interfaces.
+
+An API **may** contain many-to-many relationships, and **should** use a
+repeated field containing a list of resource paths, following the principles
+described for repeated fields in [arrays][/arrays].
+
+
+{% tab proto %}
+
+{% sample 'many_to_many_repeated.proto', 'message Book' %}
+
+{% tab oas %}
+
+{% sample 'many_to_many_repeated.oas.yaml', 'Book' %}
+
+{% endtabs %}
+
+**Note:** See [arrays](/arrays) for more information on repeated fields, including
+how to handle common issues such as atomic changes.
+
+If the use of a repeated field is too restrictive, or if more metadata is
+required along with the association, an API **may** model a many-to-many
+relationship using a sub-resource with two one-to-many associations.
+
+{% tab proto %}
+
+{% sample 'many_to_many_subresource.proto', 'message BookAuthor' %}
+
+{% tab oas %}
+
+{% sample 'many_to_many_subresource.oas.yaml', 'BookAuthor' %}
+
+{% endtabs %}
+
+**Note:** Using subresources to model an association between resources is only
+recommended if additional metadata is required in the relationship, or if the
+restrictions around the use of a repeated field preclude the use of that
+approach.
+
+<!-- prettier-ignore-start -->
+[aep-132]: ./0132.md
+[aep-144]: ./0144.md
+[aep-160]: ./0160.md
+<!-- prettier-ignore-end -->

aep/general/0124/aep.yaml

@@ -1,7 +1,7 @@
 ---
 id: 124
-state: reviewing
+state: approved
 slug: resource-association
-created: 2023-01-22
+created: 2024-03-15
 placement:
   category: resources

aep/general/0124/many_to_many_repeated.oas.yaml

@@ -0,0 +1,20 @@
+---
+openapi: 3.0.3
+info:
+  title: Library
+  version: 1.0.0
+components:
+  schema:
+    Book:
+      description: A representation of a single book.
+      properties:
+        path:
+          type: string
+          description: |
+            The path of the book.
+            Format: publishers/{publisher}/books/{book}
+        authors:
+          type: array
+          items:
+            type: string
+          description: The author or authors of the book.

aep/general/0124/many_to_many_repeated.proto

@@ -0,0 +1,18 @@
+syntax = "proto3";
+
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+
+message Book {
+  option (google.api.resource) = {
+    type: "library.googleapis.com/Book"
+    pattern: "publishers/{publisher}/books/{book}"
+  };
+
+  string path = 1 [(google.api.field_behavior) = IDENTIFIER];
+
+  // The resource paths for the book's authors.
+  repeated string authors = 2 [(google.api.resource_reference) = {
+    type: "library.googleapis.com/Author"
+  }];
+}

aep/general/0124/many_to_many_subresource.oas.yaml

@@ -0,0 +1,20 @@
+---
+openapi: 3.0.3
+info:
+  title: Library
+  version: 1.0.0
+components:
+  schema:
+    BookAuthor:
+      description: A representation of a book being written by an author.
+      properties:
+        path:
+          type: string
+          description: |
+            The path of the book.
+            Format: publishers/{publisher}/books/{book}
+        authors:
+          type: string
+          description: |
+            The author of the book.
+            Format publishers/{publishers}/authors/{author}

aep/general/0124/many_to_many_subresource.proto

@@ -0,0 +1,23 @@
+syntax = "proto3";
+
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+
+message BookAuthor {
+  // The resource pattern for BookAuthor indicates that Book is the
+  // canonical parent.
+  option (google.api.resource) = {
+    type: "library.googleapis.com/BookAuthor"
+    pattern: "publishers/{publisher}/books/{book}/authors/{book_author}"
+  };
+
+  // The resource path for the book-author association.
+  string path = 1 [(google.api.field_behavior) = IDENTIFIER];
+
+  // The resource path for the author.
+  string author = 2 [(google.api.resource_reference) = {
+    type: "library.googleapis.com/Author"
+  }];
+
+  // Other fields...
+}

aep/general/0124/multiple_many_to_one.oas.yaml

@@ -0,0 +1,18 @@
+---
+openapi: 3.0.3
+info:
+  title: Library
+  version: 1.0.0
+components:
+  schema:
+    Book:
+      description: A representation of a single book.
+      properties:
+        path:
+          type: string
+          description: |
+            The path of the book.
+            Format: publishers/{publisher}/books/{book}
+        author:
+          type: string
+          description: The author or authors of the book.

aep/general/0124/multiple_many_to_one.proto

@@ -0,0 +1,20 @@
+syntax = "proto3";
+
+import "google/api/resource.proto";
+
+message Book {
+  // The resource path pattern for Book indicates that Publisher is the
+  // canonical parent.
+  option (google.api.resource) = {
+    type: "library.googleapis.com/Book"
+    pattern: "publishers/{publisher}/books/{book}"
+  };
+
+  // The resource path for the book.
+  string path = 1 [(google.api.field_behavior) = IDENTIFIER];
+
+  // The resource name for the book's author.
+  string author = 2 [(google.api.resource_reference) = {
+    type: "library.googleapis.com/Author"
+  }];
+}