Support for ordered array query params

[nfroidure]

It would be nice to have a way to indicate that an array query parameter items should be ordered.

That way you ensure that the encoded query string will always be the same if it contains the same elements. This is useful for caching for example. Indeed a proxy cannot figure out if the query parameters elements order matter or not and lead to potential content duplication / cache busting issues.

It would give parameters definitions like that:

{
      name: 'pages',
      in: 'query',
      type: 'array',
      items: {
        type: 'number',
      },
      ordered: true,
      description: 'The pages to print',
    }

How i handle this:
https://github.com/nfroidure/strict-qs/blob/master/src/index.mocha.js#L34-L60

Seems related: #568

[nfroidure]

No thought on this ? Since the final v3 is coming i'd like to know if I have a chance to get this shipped in the spec. I can do a PR if needed.

[ePaul]

Just to understand, you want to have style: form with explode: true (both are the defaults for in: query) (e.g. [1,3,5] results in ?pages=1&pages=3&pages=5), and this ordered: true would make sure that the client never generates e.g. ?pages=3&pages=5&pages=1 instead. For ordered: false the client would be allowed to generate either, and caches which know the API schema would be allowed to return the response for one to a request for the other.

If you use explode: false, you would simply get pages=1,3,5, which might solve your problem more easily?

[nfroidure]

I can distinguish three type of item collections:

• position free sets: for example, if i want to find the users with both admin and manager roles /users?roles=admin&roles=manager. In this case the order has no importance and /users?roles=manager&roles=admin points to the same resource. This situation is not covered yet per the spec.

• sets: in this case, the collection of items is still a set but the order does matter. Let's say we wanna sort our users per region and then name: /users?sort=region&sort=name. /users?sort=name&sort=region would give a completely different result. This situation is covered by JSONSchema with the uniqueItem property.

• position free array: here, we have an array of items that can repeat and for which the order does not matter. I could not find any real world usage of it.

• array: here, we have an array of items that can repeat and for which the order does matter. Let's say we want to output a CSV of our users and for any reason have the name field printed twice in it: /users.csv?fields=name&fields=region&fields=name

Using the explode: false parameter, as far as I understand, would simply delegate the order checking to the actual operation implementation. The API definition would then loose a concept that matter to query resources in a smarter manner.

The more I think about it, the fact I order the positional free sets for caching reason is an implementation detail, the real matter is to distinguish positional collections from the other. A client UI would probably not use the same component if the position of the items matter to input them. For a positional free collection that can have 3 different items, one could use checkboxes. But if they are positional, one would use something else.

In light of it the good property name would probably be positional: boolean or unordered: boolean.

[handrews]

@nfroidure exploded arrays are done in order because arrays are ordered. Thats part of RFC6570 (which states that the explode operatior "iterates over the list" which is clearly intended to be ordered.

I don't think there's anything to be done here. I think there's an issue open with JSON Schema for being able to describe unordered sets, which is where you'd address that.

Am I missing something here?

[nfroidure]

@handrews by ordered true / false, I meant : the order is important / the order doesn't matter. Basically : [2, 3, 1, 2] is the same than [1, 2, 2, 3]. If true, you can safely use the same cache key for both (by example, by sorting items before creating the cache key), otherwise, you'll have to distinguish them and keep the original order.

An array not ordered is different of a Set since a set cannot have duplicate items. That said, maybe that a better word can name that kind of property ?

[handrews]

@nfroidure what I gather here is that there's nothing to be done regarding RFC6570 parameter expansion and ordering (we can't change that spec and that's what we reference).

For things like set vs unordered list can we close this in favor of:

• Formats for arrays #3572

which proposes format values to mark sets, multisets, and sequences?

That seems like the same concern but it's more complete and someone can open a PR for that at any time because the registries are much easier to expand than the spec. Plus, this part of the spec (Schema Object) is really the JSON Schema spec - we don't want to add more complexity to the Parameter Object list (but #1502 would allow handling the whole query string with one Schema Object, so you could then apply a format to that).

[nfroidure]

@handrews ok, let's close this then ;)