diff --git a/aip/general/0127.md b/aip/general/0127.md index 0346cbe2fb..86ccb3a6de 100644 --- a/aip/general/0127.md +++ b/aip/general/0127.md @@ -27,7 +27,9 @@ streaming. ### HTTP method and path When using protocol buffers, each RPC **must** define the HTTP method and path -using the `google.api.http` annotation: +using the `google.api.http` annotation. This annotation specifies an +[HttpRule][] for the method. (The comments in the linked proto give more +exhaustive details than this page.) ```proto rpc CreateBook(CreateBookRequest) returns (Book) { @@ -68,7 +70,7 @@ message CreateBookRequest { - RPCs **should** use the prescribed HTTP verb for custom methods, as discussed in [AIP-136][]. - RPCs **should not** use `put` or `custom`. -- The corresponding value represents the URI. +- The corresponding value represents the path in the URI. - URIs **must** use the `{foo=bar/*}` syntax to represent a variable that should be populated in the request proto. When extracting a [resource name][aip-122], the variable **must** include the entire resource name, not @@ -92,6 +94,17 @@ message CreateBookRequest { - The `body` **must not** be a `repeated` field. - Fields **should not** use the `json_name` annotation to alter the field name in JSON, unless doing so for backwards-compatibility reasons. + - In any given HTTP request, if a field is represented in both the body + and the URI, the values **must** be identical. The server behavior when + this constraint is violated is unspecified. +- Eligible fields which are not represented in the URI path or the body are mapped + to URI query parameters. + - Only singular primitive, repeated primitive, and singular message type fields + are eligible to be represented as query parameters. + - Repeated primitive fields are represented as repeated query parameters, + e.g. `...?param=A¶m=B`. + - For message type fields, each eligible leaf field is represented as a + separate query parameter, e.g. `...?foo.a=A&foo.b=B&foo.c=C`. **Note:** Bi-directional streaming RPCs should not include a `google.api.http` annotation at all. If feasible, the service **should** provide non-streaming @@ -127,11 +140,14 @@ rpc CreateBook(CreateBookRequest) returns (Book) { ## Changelog +- **2022-07-21**: Added clarification around field duplication between the + body and URI, and added query parameter mapping. - **2021-01-06**: Added clarification around `body` and nested fields. - **2019-09-23**: Added a statement about request body encoding, and guidance discouraging `json_name`. +[HttpRule]: https://github.com/googleapis/googleapis/blob/master/google/api/http.proto [aip-121]: ./0121.md [aip-122]: ./0122.md [aip-131]: ./0131.md