AIP-4222

Routing headers

In some situations, a gRPC API backend is able to route traffic more efficiently if it knows about some values in the request; however, the request payload can not be reasonably deconstructed on the wire to perform that routing.

Guidance

Code generators should look at URI-based variables declared in the google.api.http annotation and transcribe these into the x-goog-request-params header in unary calls. A URI-based variable is a variable declared as a key in curly braces in the URI string. For example:

rpc CreateTopic(CreateTopicRequest) {
  option (google.api.http).post = "{parent=projects/*}/topics";
}

Note: the ommission of a path segment in the variable template, {parent} for example, is equivalent to {parent=*} and should be parsed.

In this case, the applicable variable is parent, and it refers to the parent field in CreateTopicRequest. When the user provides an instance of CreateTopicRequest to the method (or once the client library has built it, in the case of method overloads), the client library must extract the key and value, and append them to the x-goog-request-params header. Both the key and the value must be URL-encoded per RFC 6570 §3.2.2. This can be done with standard library URL encoding. For example, adding this header to a gRPC request in Go:

md := metadata.Pairs("x-goog-request-params",
  url.QueryEscape("parent") + "=" + url.QueryEscape(req.GetParent()))

Much like URL parameters, if there is more than one key-value pair, the & character is used as the separator. At runtime, if a named parameter is unset on the request message, it should not be included in the headers.

If the google.api.http annotation contains additional_bindings, these patterns should be parsed for additional request parameters. Fields not duplicated in the top-level (or additional_bindings) pattern should be included in request parameters, encoded in the same way.

Note: There is no additional annotation used for this; the presence of the key in any of the standard fields (get, post, put, patch, delete) on the google.api.http annotation is sufficient.

Changelog

• 2020-04-21: Explicitly parse path variables missing a trailing segment.
• 2019-11-27: Include additional_bindings as a request parameter source.
• 2019-06-26: Fix wording and example of key-value pair encoding.
• 2019-06-20: Specify encoding of header parameters.