diff --git a/aep/general/0231/aep.md.j2 b/aep/general/0231/aep.md.j2 index d5c7b1ad..d00a20cb 100644 --- a/aep/general/0231/aep.md.j2 +++ b/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 @@ -45,7 +46,8 @@ pattern: ```proto rpc BatchGetBooks(BatchGetBooksRequest) returns (BatchGetBooksResponse) { option (google.api.http) = { - get: "/v1/{parent=publishers/*}/books:batch-get" + post: "/v1/{parent=publishers/*}/books:batch-get" + body: "*" }; } @@ -55,7 +57,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 +79,8 @@ 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 +162,14 @@ 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 verb? + +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 diff --git a/aep/general/0231/batchget.oas.yaml b/aep/general/0231/batchget.oas.yaml index f9f937ee..fd836bf1 100644 --- a/aep/general/0231/batchget.oas.yaml +++ b/aep/general/0231/batchget.oas.yaml @@ -10,22 +10,30 @@ paths: required: true schema: type: string - get: + post: operationId: BatchGetBooks description: Get multiple books in a batch. - parameters: - - name: paths - in: query - required: true - description: >- - The paths of the books to retrieve. Format: - publishers/{publisherId}/books/{book_id} - schema: - type: array - minItems: 1 - maxItems: 1000 - items: - type: string + 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 @@ -60,9 +68,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