What is a 2-dimensional key-value format that Api Blueprint can understand?

Question

I'm developing api documentation for a RESTful search API using Api Blueprint. I would like to be able to pass filters to the API so I can assemble:

filter[filtername1]=filtervalue1
filter[filtername2]=filtervalue2

Per this question, I'm using percent encoded square brackets, but unlike this question, it's not possible for us to describe every possible key name:

How to format hash-based parameters in the URL when creating Blueprint API doc?

I want the key name to be variable, since it could be any field in the source data. Does this work?

## Key-Value-Test [/api/v1/keyvaluetest?term={term}&filter%5B{field_name}%5D={field_value}]

+ term
+ filter_field
+ filter_value

Is there a recommended format for a two-dimensional array like this? It doesn't seem like this would work in Dredd because + filter_field doesn't really match filter[filter_field]

Grunion

Answer 1

API Blueprint uses URI Templates standard. There are ways to express and expand arrays (see section 3.2.1), however, it expects "standard URI approach", meaning the URI would be expanded as follows:

/api/v1/keyvaluetest?term=yourterm&filter=filtervalue1&filter=filtervalue2

which is a "standard" way of doing arrays, except the most popular web language popularised your way back in 2000s.

The templates are designed for expansion: give it a bunch of variables and a string, and you'll get a properly-formatted string. As far as I am aware, there is no "wild match" (inserting pattern-match variables at a certain position in string).

The only solution I can think of within the realm of URL templates would be taking advantage of explosion modifier (see composite values):

/api/v1/keyvaluetest{?keys*}

which, given associative array of values [(filter%5Bfiltername1%5D, filtervalue1), (filter%5Bfiltername2%5D, filtervalue2) ] should expand properly.

However, I am not sure how to specify those in MSON as I don't think there is a support for "dynamic keys" and I think most of the tooling wouldn't handle it (yet).

Might be worth asking.

Envelop

Answer 2

I am afraid that API Blueprint and Apiary does not yet allow these kind of dynamic URL definitions.

API Blueprint and Apiary only allows URI Templates as defined in RFC 6570

The following URI Template is not valid according to that RFC

GET /resource?year={year}&month={month}

You can change the URL to define something like the following:

## Key-Value-Test [/api/v1/keyvaluetest{?term,field_name,field_value}]

+ Parameters
    + term: a
    + field_name: b
    + field_value: c

There are two caveats with this method:

• You can only give one field name and field value for the parameters. If you want more field parameters, you have to extend the URL.
• You have to change the API url which I don't think you would want to.

Please start a feature request at http://support.apiary.io if you have any.

Hydrocortisone

It's probably worth mentioning that @PavanKumarSunkara is an Apiary developer. – Drawstring

Note the URI template does not seems to be correct. Instead of "?term={term}" you want just "{?term}" see github.com/apiaryio/api-blueprint/blob/master/… – Vaillancourt

Also related – support.apiary.io/knowledgebase/articles/… – Vaillancourt