Dynamic query parameters

[tim-peters]

As far as I know, there are some rare cases where it is indispensable to use query parameters where field and value are both dynamic. For example it is much simpler to filter by more than one attribute with query parameters than with a complex URL hierarchy (and/or multiple requests).

Here is an example:

GET /cars?brand=mercedes&color=red

Please Notice, that brand and color could be any attributes of the cars object, while mercedes and red could be any value of those attributes.

Unfortunately I haven't found a way to document this with API Blueprint properly yet. There is neither anything in the documentation about dynamic query parameters nor have I found a question concerning this.

All of the following ways are invalid:

## Filters [/cars{?field=variable}]
+ Parameters
    + field: brand (optional, string)
    + variable: mercedes (optional, string)

## Filters [/cars{?field}={variable}]
+ Parameters
    + field: brand (optional, string)
    + variable: mercedes (optional, string)

The only valid method yet is to list all possible fields as separated parameters. IMHO this isn't handy to write nor is it easy to understand for users. Does anyone have an idea on how to document this properly with API Blueprint?

[erunion]

Are you just trying to document an enum? I'm having a hard time understanding what you're trying to do here.

[tim-peters]

No, I'm not. I am trying to document the ability to filter by the value of any attribute of an object.

Think of a database with cars (object). cars have the attributes color, brand, amount_of_wheels etc. The user should be able to filter by all of those attributes with query parameters. As far as I can see the only way to document this yet is:

## Filters [/cars{?cars,brand,amount_of_wheels}]
+ Parameters
    + color: red (string)
        + Members
            + red
            + blue
            + green
            + grey
            ...
    + brand: mercedes (string)
        + Members
            + mercedes
            + nissan
            + citroen
            ...
    + amount_of_wheels: 3 (number)
        ...

Now try to imagine an object with up to 100 attributes and this gets really messy. I'm looking for an easier and clearer way to document those dynamic query parameters.

[Kyslik]

I am also interested in this.

Structure we are using is following users/?filter-username=!kyslik&filter-name=~tim, note filter prefix (since using pure column name is not good, we may have column with name page, size and that would conflict with pagination and limit). You may see operators ! - not, ~ - like, + - gt, - - lt.

How would I document that?