feat(231): allow POST HTTP verb

aep/general/0231/aep.md.j2

@@ -10,14 +10,15 @@ APIs **may** support batch get to retrieve a consistent set of resources.
 
 - The method's name **must** begin with `BatchGet`. The remainder of the method
   name **must** be the plural form of the resource being retrieved.
-- The HTTP verb **must** be `GET`.
+- The HTTP verb **must** be `GET` or `POST`.
 - The HTTP URI **must** end with `:batch-get`.
 - The URI path **must** represent the collection for the resource, matching the
   collection used for simple CRUD operations. If the operation spans parents, a
   [wilcard](./reading-across-collections) **may** be accepted.
-- There **must not** be a request body.
+- When the HTTP verb is `GET`, there **must not** be a request body.
   - If a GET request contains a body, the body **must** be ignored, and **must
     not** cause an error.
+- When the HTTP verb is `POST`, there **must** be a request body.
 
 ### Request
 
@@ -46,6 +47,10 @@ pattern:
 rpc BatchGetBooks(BatchGetBooksRequest) returns (BatchGetBooksResponse) {
   option (google.api.http) = {
     get: "/v1/{parent=publishers/*}/books:batch-get"
+    additional_bindings: {
+      post: "/v1/{parent=publishers/*}/books:batch-get"
+      body: "*"
+    }
   };
 }
 
@@ -55,7 +60,7 @@ message BatchGetBooksRequest {
   // If this is set, the parent of all of the books specified in `paths`
   // must match this field.
   string parent = 1 [
-    (aep.api.field_info) = { resource_reference: [ "library.com/book" ], field_behavior: [ FIELD_BEHAVIOR_OPTIONAL ] }
+    (aep.api.field_info) = { resource_reference: [ "library.com/publisher" ], field_behavior: [ FIELD_BEHAVIOR_OPTIONAL ] }
   ];
 
   // The paths of the books to retrieve.
@@ -77,7 +82,10 @@ message BatchGetBooksRequest {
   - The field **should** identify the [resource type][aep-122-parent] that it
     references.
   - The comment for the field **should** document the resource pattern.
-- There **must not** be a body key in the `google.api.http` annotation.
+- When the HTTP verb is `GET`, there **must not** be a body key in the
+  `google.api.http` annotation.
+- When the HTTP verb is `POST`, there **must** be a body key in the
+  `google.api.http` annotation.
 
 {% tab oas %}
 
@@ -159,6 +167,19 @@ get either succeeds for all requested resources or fails. When supported, the
 method must define a boolean parameter `transactional` that the user must
 specify with the value `true` to request a transactional operation.
 
+## Rationale
+
+### Why allow both `POST` and `GET` HTTP verbs?
+
+In AEP-2026, only the `GET` verb was allowed, originally to ensure cacheability
+of the request. However, query parameters along to specify a large number of
+IDs can face practical limitations, such as maximum URL length in a given
+browser.
+
+As such, `POST` is accepted as an alternative method. Although the IETF is
+working on a `QUERY` HTTP method, this is not generally implemented in API
+gateways, and therefore `POST` acts as more practical alternative.
+
 ## Changelog
 
 - **2024-04-22:** Adopt from Google AIP https://google.aip.dev/231 with the

aep/general/0231/batchget.oas.yaml

@@ -40,6 +40,44 @@ paths:
                       oneOf:
                         - $ref: '#/components/schemas/Book'
                         - $ref: '#/components/schemas/Error'
+    post:
+      operationId: BatchGetBooksPost
+      description: Get multiple books in a batch.
+      requestBody:
+        description: |
+          List of book resource names to retrieve. Each entry must follow the
+          format `publishers/{publisherId}/books/{book_id}`.
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - paths
+              properties:
+                paths:
+                  type: array
+                  description: |
+                    The paths of the books to retrieve. Format:
+                    `publishers/{publisherId}/books/{book_id}`.
+                  minItems: 1
+                  maxItems: 1000
+                  items:
+                    type: string
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  results:
+                    type: array
+                    items:
+                      oneOf:
+                        - $ref: '#/components/schemas/Book'
+                        - $ref: '#/components/schemas/Error'
 components:
   schemas:
     Book:
@@ -60,9 +98,9 @@ components:
           description: The title of the book.
         authors:
           type: array
+          description: The author or authors of the book.
           items:
             type: string
-          description: The author or authors of the book.
         rating:
           type: number
           format: float