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

Author: jskeet

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
@@ -81,7 +81,8 @@ message CreateBookRequest {
 - The `body` key defines which single top-level field in the request will be
   sent as the HTTP body. If the body is `*`, then this indicates that the
   request object itself is the HTTP body. The request body is encoded as JSON
-  as defined by protocol buffers' canonical [JSON encoding][].
+  as defined by protocol buffers' canonical [JSON encoding][]. Fields encoded
+  in the URI
   - RPCs **must not** define a `body` at all for RPCs that use the `GET` or
     `DELETE` HTTP verbs.
   - RPCs **must** use the prescribed `body` for Create ([AIP-133][]) and Update
@@ -92,6 +93,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&param=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 +139,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`.