[Questions]: REST API pagination keys contain a dot which is not supported in YAML

[kopeboy]

Is there an existing issue for this?

• I have searched the existing issues

What happened?

Using dots inside keys is not a good practice imho since they are usually used to separate keys!

I can't execute 44 different queries when defining my HTTP API in YAML, as they all contain pagination.foo and there is no way of escaping the dot in a YAML key.

There is a workaround (adding an uri parameter by default, like ?pagination.limit={limit}), but that's not ideal.

limit is not a property of a pagination object (URL parameters are flat), so I find this confusing and limiting compatibility and ease of integration of the API.

Can we use the common separator "_" everywhere instead, as in proposal_id, proposal_status, etc, instead of using "." only for the pagination query parameters?
🙏

Cosmos SDK Version

main

How to reproduce?

I'm copying a useful subset of Cosmos SDK API commands as Guzzle Service Descriptions (the most common HTTP Client for PHP, which is still the most used language on the web) in simple YAML files, to allow non-developers get governance proposals, smart contracts data, etc. on their own millions websites by filling forms & clicking buttons on the GUI.

Here you can see both the commented error-generating definition and the workaround when using this Drupal module

The error I get is "Key contains a dot which is not supported", and an extensive search did not yield solutions as it seems keys are simply not supposed to be escaped in YAML.
Even in JSON, for example to parse responses with jq, one would need to put double quotes inside single quotes to get the dotted property, which is not user-friendly.

[facundomedica]

Hey @kopeboy ! Have you seen this swagger yaml? https://github.com/cosmos/cosmos-sdk/blob/main/client/docs/swagger-ui/swagger.yaml

[kopeboy]

Oh nice, I did not! Thank you @facundomedica, I'll try that.

[kopeboy]

Actually defining the array and/or the name didn't work either.

The workaround someone else gave me was:

    parameters:
      limit:
        location: query
        description: Pagination limit
        type: string
        required: false
        default: '10'
        sentAs: "pagination.limit"

I would still consider removing the dot to make integrations easier.
Thank you

[tac0turtle]

i believe this is grpc-gateway and how it handles parameters. Im not sure we can adjust this, also it would be a large breaking change for clients. We would end up needing to support . and _ which is not ideal.

Have you looked into the tooling around grpc-gateway to see if there is anything that can be done there?

[kopeboy]

@tac0turtle You mean to find a solution upstream?
Cause I'm just trying to use the nodes' REST API as a client, why would I need to use a grpc-gateway...

[tac0turtle]

grpc-gateway is the rest api, we dont write a separate rest api to the grpc its generated for us. If grpc-gateway supports what you are asking we can make changes if not then you will need to talk to the maintainers of that repo