From 99a3a8ae1b93f231c219404317eef8eeb249b073 Mon Sep 17 00:00:00 2001 From: Olivier Cano Date: Sun, 7 Jun 2026 15:36:09 +0200 Subject: [PATCH 1/2] feat(231): allow `POST` HTTP verb Signed-off-by: Olivier Cano --- aep/general/0231/aep.md.j2 | 21 +++++++++++++---- aep/general/0231/batchget.oas.yaml | 38 ++++++++++++++++++------------ 2 files changed, 39 insertions(+), 20 deletions(-) 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 From b0aa93737b3484b86bfa223d06fc2f154009df9e Mon Sep 17 00:00:00 2001 From: Yusuke Tsutsumi Date: Fri, 24 Jul 2026 22:01:55 -0700 Subject: [PATCH 2/2] feat(0231): keep GET example alongside POST example in samples and fix typo --- aep/general/0231/aep.md.j2 | 24 +++++++++++++++------- aep/general/0231/batchget.oas.yaml | 32 +++++++++++++++++++++++++++++- 2 files changed, 48 insertions(+), 8 deletions(-) diff --git a/aep/general/0231/aep.md.j2 b/aep/general/0231/aep.md.j2 index d00a20cb..4051e046 100644 --- a/aep/general/0231/aep.md.j2 +++ b/aep/general/0231/aep.md.j2 @@ -46,8 +46,11 @@ pattern: ```proto rpc BatchGetBooks(BatchGetBooksRequest) returns (BatchGetBooksResponse) { option (google.api.http) = { - post: "/v1/{parent=publishers/*}/books:batch-get" - body: "*" + get: "/v1/{parent=publishers/*}/books:batch-get" + additional_bindings: { + post: "/v1/{parent=publishers/*}/books:batch-get" + body: "*" + } }; } @@ -79,8 +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. -- 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. +- 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 %} @@ -164,11 +169,16 @@ specify with the value `true` to request a transactional operation. ## Rationale -### Why allow both `POST` and `GET` HTTP verb? +### 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. +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. +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 diff --git a/aep/general/0231/batchget.oas.yaml b/aep/general/0231/batchget.oas.yaml index fd836bf1..4422da24 100644 --- a/aep/general/0231/batchget.oas.yaml +++ b/aep/general/0231/batchget.oas.yaml @@ -10,9 +10,39 @@ paths: required: true schema: type: string - post: + get: 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 + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + results: + type: array + items: + 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