Skip to content

feat(231): allow POST HTTP verb #415

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kindermoumoute wants to merge 1 commit into
base: main
Choose a base branch
from
+15 −5
Open

feat(231): allow POST HTTP verb #415

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 15 additions & 5 deletions aep/general/0231/aep.md.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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: "*"
};
}

Expand All @@ -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.
Expand All @@ -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 %}

Expand Down Expand Up @@ -159,6 +162,13 @@ 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 allowing both `POST` and `GET` HTTP verb?

@toumorokoshi toumorokoshi Jun 12, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### Why allowing both `POST` and `GET` HTTP verb?
### Why allow both `POST` and `GET` HTTP verb?

Just a grammatical nit.


- Allowing the `POST` HTTP verb address practical limitations such as URL length constraints (e.g., 2048 characters).
- Allowing the `GET` HTTP verb maintains backward compatibility and cacheability.

@toumorokoshi toumorokoshi Jun 13, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

I think it's valuable to elaborate on the full conversation - oftentimes people come to the rationale section to hear about the "why" in depth, including context on pros / cons and alternatives.

## Changelog

- **2024-04-22:** Adopt from Google AIP https://google.aip.dev/231 with the
Expand Down