CODEWITHSUNDEEP
apiblueprintapiary.ioapiary
James H
James H

Reputation: 1832

API Bluprint documentation of query string parameters with Rails' array notation

I'm not having much luck trying to use resourceful documentation for an API URI which uses Rails' array parameter notation

For example (the unencoded URL for clarity):

/api/v2/profiles?ids[]=35&ids[]=47&ids[]=12&ids[]=132

and the actual encoded URL:

/api/v2/profiles?ids%5b%5d=35&ids%5b%5d=47&ids%5b%5d=12&ids%5b%5d=132

This does not work:

## Profiles [/api/v2/profiles{?ids%5b%5d*}]

### List profiles [GET]

+ Parameters

    + ids%5b%5d (required, number) ... ID of a profile to fetch. May be specified multiple times.

Testing this against the beta 3 column layout. Have not tried it with the old layout.

Upvotes: 3

Views: 3351

Answers (2)

JeremyTM
JeremyTM

Reputation: 633

This works well as a solution.

### Get a group of specified items [GET /statistics?ids[]={id1}&ids[]={id2}]

+ Parameters
    + id1 (number, `1`)
    + id2 (number, `2`)
    + idx (number, `any ID`)

+ Response 200 (application/json; charset=utf-8)

        {
            "items": [
                {
                    "id": 1,
                    "value": "Item 1"
                },
                {
                    "id": 2,
                    "value": "Item 2"
                },
            ]
        }

It clearly communicates what the usage is, as well as making things clear and useable in the interactive documentation.

Upvotes: 2

Zdenek
Zdenek

Reputation: 3693

At this moment I would run the parameter (description) without the square brackets like so:

# Rails Params

## Profiles [/api/v2/profiles{?ids%5b%5d*}]

### List profiles [GET]

+ Parameters
    + ids (required, number) ... ID of a profile to fetch. May be specified multiple times.

        For example: `profiles?ids[]=35&ids[]=47&ids[]=12`


+ response 204

You can find the example Rendered in Apiary here.

However this situation needs to be improved. I have created the issue on the API Blueprint parser to track this.

Upvotes: 6

Related Questions