diff --git a/aip/general/0136.md b/aip/general/0136.md index dbb52c26f..c1edb8a34 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 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