diff --git a/aep/general/0231/aep.md.j2 b/aep/general/0231/aep.md.j2 index d5c7b1ad..4051e046 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 @@ -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 diff --git a/aep/general/0231/batchget.oas.yaml b/aep/general/0231/batchget.oas.yaml index f9f937ee..4422da24 100644 --- a/aep/general/0231/batchget.oas.yaml +++ b/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