[Docs/Examples] No docs/examples for path parameter curly bracket syntax

[AudriusButkevicius]

📚 Documentation

Looking at #720
it seems the path patterns support some sort of {foo=bar} templating, but I can't seem to find any docs about it, what it does, how it works, or it's use in any examples.

Furthermore, there is no indication of where users can ask questions (whether it's the issue tracker, forum, mailing list etc).

Hence I am dumping it here:

I'd like to implement a rpc method with optional parameters for paging.
Namely:

GET /books = returns all books
GET /books/{page}/{per_page} = returns paginated books

I assume I might be able to do something like:

get: "/books/{page=0}/{per_page=0}

But it seems the swagger spec generated has both parameters as required and not optional and default value is nowhere to be seen, so I assume this doesn't do what I want.

Does this really need to be two separate grpc methods?
I guess I could have additional_bindings with the path parameters, but then I get an ugly GetBooks, GetBooks2 operations.
Is there a way to control the operation name for the additional binding, so I could call it GetBooksPaginated or something?

[johanbrandhorst]

Hi Audrius, sorry for the confusion caused here. This optional syntax is for specifying a field to include a non-variable part of the, i.e:

get: "/v1/{name=messages/*}"

Means that the variable name will have the value messages/123456 when the method is invoked with the path GET /v1/messages/123456. These definitions come from http.proto, which is the spec we use for parsing the annotations.

You're absolutely right that this should be more visible and I'd love to review a PR that adds this note in a suitable place in the documentation (I think the README would be a good place to start). What do you think?