Add detail for gRPC/HTTP transcoding

[jskeet]

• Define which fields are mapped to query parameters (and how)
• Specify behavior (and limitations) for fields represented in
  both the body and the URI

[vchudnov-g]

LGTM, just some suggestions for links to additional info.

[vchudnov-g]

(URN, in the nomenclature of https://en.wikipedia.org/wiki/Uniform_Resource_Identifier, though it seems this term is not commonly used)

[jskeet]

I suspect that far more readers will understand "path in the URI" than "URN".

[vchudnov-g]

Agreed. (Hence the parentheses)

[vchudnov-g]

It might be useful to include a reference to https://developers.google.com/protocol-buffers/docs/proto3#json, which has more details (and may get updated based on our parallel work)

[jskeet]

That's already referenced earlier in the body part: "The request body is encoded as JSON
as defined by protocol buffers' canonical JSON encoding" where "JSON encoding" is a link.

[vchudnov-g]

It would be good to link to the source of truth https://github.com/googleapis/googleapis/blob/dbfbfdb38a2f891384779a7ee31deb15adba6659/google/api/http.proto#L61 .... but is there a web-friendly, auto-up-to-date view of this somewhere we can use?

[jskeet]

I've added a link to the proto (in the master branch, which will be redirected accordingly if we rename it to main) earlier - I think that's probably clearer than trying to link to individual bits of documentation for each section.

[vchudnov-g]

nit: Consider simpler wording: s/are eligible to be/may be/

[jskeet]

I'd prefer to keep it as "eligible" as "may" suggests something that's optional - a client might or might not decide to encode some fields as URI query parameters. In reality, a client must do that, because the fields are eligible to be encoded. Happy to noodle on alternatives to "eligible" - I'd just prefer to avoid "may".

[vchudnov-g]

Oh, I see what you mean. On a naive read, "eligible" registered to me as something you can choose to do, i.e. "may". But you are using it in an algorithmic sense, tying back to your previous line.

Could we say instead:

Fields which are not represented in the URI path or the body are mapped to URI query parameters if and only if they 
are singular primitive, repeated primitive, or singular message type fields.
- Repeated primitive...
- For message-type fields....

And that also brings up a question to clarify: what about repeated message fields? Should it be an error for there to be an http binding that does not map them to the body, since they can't be represented in the path or query params and so would incur data loss if non-empty?

[jskeet]

I've added a new commit with a link to http.proto.

[jskeet]

I suspect that far more readers will understand "path in the URI" than "URN".

[jskeet]

That's already referenced earlier in the body part: "The request body is encoded as JSON
as defined by protocol buffers' canonical JSON encoding" where "JSON encoding" is a link.

[jskeet]

I'd prefer to keep it as "eligible" as "may" suggests something that's optional - a client might or might not decide to encode some fields as URI query parameters. In reality, a client must do that, because the fields are eligible to be encoded. Happy to noodle on alternatives to "eligible" - I'd just prefer to avoid "may".

[jskeet]

I've added a link to the proto (in the master branch, which will be redirected accordingly if we rename it to main) earlier - I think that's probably clearer than trying to link to individual bits of documentation for each section.