Api-blueprint: Propose array in parameters

[huiyiqun]

## Videos [/video{?status}]

+ Parameters
    + status (array[int])

means:

/video?status[]=1&status[]=2

or:

/video?status=1&status=2

[zdne]

@huiyiqun I would definitely love to simplify describing arrays of URI query parameters – lots of framework seems to be using reserved square brackets characters ([ and ]) in URI anyway.

Are you proposing that declaring a URI query parameter as an array (e.g. status (array)) means the query parameter can appear multiple times or that it has [ ] appended to its name ?

What about parameter names like user[email] and user[password]?

[honzajavorek]

I'd vote for being unambiguous, thus explicitly dealing with the "or" in the original proposal. I think the array could just mean _this parameter MAY appear multiple times_. It's up to the blueprint/API authors whether it's

• status[] (array[int]) meaning ?status[]=x&status[]=y, or
• status (array[int]) meaning ?status=x&status=y.

_Note: the first notation, status[], would probably need additional escaping backticks due to presence of reserved characters, [ and ], but I left them out as it was hard to write them nested in Markdown comment here._

What about parameter names like user[email] and user[password]?

Hmm, this never came to my mind! Do you see this often in the wild? To me, it seems to me more like a mapping, thus it's beyond the capabilities of array and if we are going to support it, we should probably support it as object. However, it seems like a thin ice to me... we should think through all the implications before introducing object in URI parameters - it can be a rabbit hole.

[pksunkara]

status[] (array[int]) meaning ?status[]=x&status[]=y

I really really don't like this. I think there are three separate conventions people use:

1. Array is represented as status[]=x&status[]=y
2. Array is represented as status[0]=x&status[1]=y
3. Array is represented as status=x&status=y

While the 1 and 2 are the popular ones, you can still find 3 in the wild. When people use one of the first two, the third one generally represents overwriting a parameter (which I think is conceptually correct).

Objects are generally represented as user[password]=password&user[username]=pavan. So, they should not be an issue except for the cases where servers doesn't support them.

[huiyiqun]

Reserved square brackets characters is a de-facto standard for most framework such as expressjs and php.

As @honzajavorek says, '[]' needs additional escape and I feel it hard to comprehend.

What's more, I think status=x&status=y is not a good method to express array for it's not apparent whether status=x is an array which has only one element or just a string.

[honzajavorek]

I think status=x&status=y is not a good method to express array

The problem is that I think we cannot make assumptions based on our thoughts like this. I have also my ideals about how APIs should look like, but people will want to describe their APIs in API Blueprint regardless of what we think is the best approach. We can champion a certain way to specify something, but we shouldn't prevent other approaches, even "ugly" ones, at the same time. Sometimes it also happens a valid use case it provided for the "ugly" approach and the author then may struggle how deal with obstacles we prepared for them.

If status (array) would mean the parameter can appear multiple times and [] should be added automatically, what would be the notation for status appearing multiple times but without any additional brackets?

[pksunkara]

what would be the notation for status appearing multiple times but without any additional brackets

IIRC, this means that status parameter is being overwritten according to some of the technical stuff I read before when I was working on https://github.com/pksunkara/alpaca. I do not recall where I read it though. We definitely need to do some research.

[huiyiqun]

According to the RFC of uri template

{?list*} means ?list=1&list=2

[] is a tag but not a standard, it SHOULD NOT be forced over users.

But there is so many developers take [] as tag, is it possible that

• list* means ?list=A&list=B
• list[] means ?list[]=A&list[]=B
• list[*] means ?list[1]=A&list[2]=B

WHITHOUT needing escape?

[honzajavorek]

status parameter is being overwritten

Not to my knowledge. You can specify how many values you want for a single parameter like this and you can normally get them all in server code. I've seen it implemented, I've seen it in frameworks. The [] is just a handy convention introduced maybe by PHP, but the HTTP is AFAIK working simply in the way that you can provide multiple values for any parameter and status[] vs. status is just your naming and it's up to you what you'll do with it. If you override them, it's your own implementation. That's why, for instance in Flask, you get MultiDict structure if you request URL params. It behaves like regular 1:1 mapping for common cases, but it also handles multiple values for the same key.

[huiyiqun]

according to this RFC, I think this solution is general:

## Videos [/video{?status}]

+ Parameters
    + status (array[int])

means:

/video?status=1,2

## Videos [/video{?status*}]

+ Parameters
    + status (array[int])

means:

/video?status=1&status=2

## Videos [/video{?status[]*}]

+ Parameters
    + `status[]` (array[int])

means:

/video?status[]=1&status[]=2

[huiyiqun]

So what about the * syntax from RFC6570?

Or maybe take use of some general purpose library like this

[huiyiqun]

status parameter is being overwritten

yes, whether status is overwritten or of multiple value is decided by the server-end implementation (Or maybe decision of server-end framework, even I do not know such framework).

[zdne]

I see this as converging to what is being discussed in #252 . See my latest proposal there https://github.com/apiaryio/api-blueprint/issues/252#issuecomment-132139642

[zdne]

RFC proposal of syntax addressing this issue: https://github.com/apiaryio/api-blueprint-rfcs/pull/3.

Please track and comment on the RFC.

Thank you!