Skip to content

chore(AIP-136): add rationale around use of POST #1627

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

Merged
jskeet merged 2 commits into from
Jun 18, 2026
+13 −1
Merged

chore(AIP-136): add rationale around use of POST #1627

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4e497f1
chore: add rationale to AIP-136 around use of POST
jskeet Jun 18, 2026
85419f6
Update aip/general/0136.md
jskeet Jun 18, 2026
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
14 changes: 13 additions & 1 deletion aip/general/0136.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ services. The bullets below apply in all three cases.
considered), a custom `CreateBookLongRunning` method could be introduced.
- The HTTP method **must** be `GET` or `POST`:
- `GET` **must** be used for methods retrieving data or resource state.
- `POST` **may** be used for data retieval methods if the request payload could
- `POST` **may** be used for data retrieval methods if the request payload could
exceed URL size limitations, thus requiring a `body`.
- `POST` **must** be used if the method has side effects or mutates resources
or data.
Expand Down Expand Up @@ -159,6 +159,18 @@ read data have first-class concepts in some clients (DataSources in
Terraform) and clearly indicate to a user which methods can be called
without risk of runtime impact.

Allowing `POST` to be used for requests which would otherwise be made using
`GET` is a convenience:

- It avoids large query strings leading to requests which violate URL size
limitations.
- It allows clients to implement a single way of serializing request data, or
at least avoids them from having to implement complex rules for repeated
fields etc.
- It allows RPCs which might normally be simple to still contain data for
complex situations where that data may not be representable via query
parameters.

### Disallowing prepositions

Generally, method names with prepositions indicate that a new method is being
Expand Down
Loading