support custom HTTP Query URI names to make a nicer UX for deeply nested messages

[jstrachan]

🚀 Feature

protobuf prefers composition of messages instead of inheritance. Its very common for HTTP GET requests to take common nested filter messages which then leads to a verbose URI.

e.g. if you use a common Filter object (for search text, sort, pagination etc) in SomeRequest then your HTTP GET URI would be something like ?filter.query=foo&filter.sort=ASC&filter.page=1

in protobuf we can already configure json marshalling names via the json tag. It would be nice to be able to support a query tag for providing a custom HTTP GET query URI parameter name used when exposing the service over HTTP GET.

We can then leave the POST / proto / JSON encoding alone but have nicer GET URIs if required. e.g. ?q=foo&sort=ASC&page=1

I've an experimental PR on the way soon that implements this to see what folks think...

[jstrachan]

I've submitted a PR but I've not yet figured out the magic permutations to get me past the CLA checker...

[johanbrandhorst]

Hi James, thanks for the issue. I'm going to be frank, I don't think this functionality belongs in this project. However, that's not to say that your PR isn't addressing a real problem that users have. I'm thinking this could make a cool example of how you can customize the grpc-gateway's query parameter parser outside of the default behavior. As far as I can tell, there's nothing in your PR that can't be covered with a custom QueryParameterParser and some post-processing of the generated files (as you're already doing with protoc-gen-gotag). What I'd like to maybe get out of this would be a little section of our docs that could show this in action, rather than deeply integrated with the gateway itself.

What do you think?

[jstrachan]

@johanbrandhorst I'd missed that the QueryParameterParser was pluggable; I'll have a look at making it a separate parser implementation.

The trickier thing is I was going to then supply another PR to modify the openapi generation to support the new Query URI names so things are consistent across the back end + front end.

I'll look into its relatively easy to add some kind of plugin there too maybe...

[RangelReale]

@jstrachan I'm interested in this also, I have a legacy API that I would like to map to new GRPC endpoints, and not being able to customize how query parameters are handled will prevent a lot of things of being converted. Did you find any good solution?