From 4e497f127605a2975529cb3ea1d9ed6f1c15c9fc Mon Sep 17 00:00:00 2001 From: Jon Skeet Date: Thu, 18 Jun 2026 11:39:45 +0000 Subject: [PATCH 1/2] chore: add rationale to AIP-136 around use of POST Admittedly this is more general than custom methods, but probably fits here as well as anywhere else. --- aip/general/0136.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/aip/general/0136.md b/aip/general/0136.md index dbb52c26f..f57798cb1 100644 --- a/aip/general/0136.md +++ b/aip/general/0136.md @@ -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. @@ -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 violated 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 From 85419f64e7ee2cb8abfb0037fa0c535e50a60f99 Mon Sep 17 00:00:00 2001 From: Jon Skeet Date: Thu, 18 Jun 2026 17:05:27 +0100 Subject: [PATCH 2/2] Update aip/general/0136.md Co-authored-by: Noah Dietz --- aip/general/0136.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aip/general/0136.md b/aip/general/0136.md index f57798cb1..c1edb8a34 100644 --- a/aip/general/0136.md +++ b/aip/general/0136.md @@ -162,7 +162,7 @@ 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 violated URL size +- 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