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 URL-based variables declared in the google.api.http annotation and transcribe these into the x-goog-request-params header in unary calls. A URL-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";
}

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.

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

  • 2019-06-20: Specify encoding of header parameters.
  • 2019-06-26: Fix wording and example of key-value pair encoding