From 4c4ffa43f958d23546398df5d8430bbf16d12d5a Mon Sep 17 00:00:00 2001 From: Jon Skeet Date: Thu, 21 Jul 2022 12:50:20 +0100 Subject: [PATCH 1/2] Add detail for gRPC/HTTP transcoding - Define which fields are mapped to query parameters (and how) - Specify behavior (and limitations) for fields represented in both the body and the URI --- aip/general/0127.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/aip/general/0127.md b/aip/general/0127.md index 0346cbe2fb..d3012341f1 100644 --- a/aip/general/0127.md +++ b/aip/general/0127.md @@ -68,7 +68,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 +92,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,6 +138,8 @@ 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`. From 1747ffeeb7817aebdaf6ba46bc24e406e054eb5a Mon Sep 17 00:00:00 2001 From: Jon Skeet Date: Fri, 22 Jul 2022 12:10:20 +0100 Subject: [PATCH 2/2] Address review comments --- aip/general/0127.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/aip/general/0127.md b/aip/general/0127.md index d3012341f1..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) { @@ -145,6 +147,7 @@ rpc CreateBook(CreateBookRequest) returns (Book) { 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