3

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.

James H
  • 1,824
  • 22
  • 23

2 Answers2

6

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.

Zdenek
  • 3,653
  • 27
  • 34
2

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.

JeremyTM
  • 593
  • 6
  • 17
  • You cannot supply square brackets directly like that. Doing so brings up the error: "The URI template contains square brackets, please percent encode square brackets as %5B and %5D" – RemoteCTO Jun 24 '15 at 07:48
  • I know. But to get quality, pleasing documentation that does really well at communicating the use of my API (which is the point, right?), we can go beyond the intentions of Apiary and put up with a few errors when it still compiles and works fine. – JeremyTM Jun 25 '15 at 08:50