Usage of `-` and `+` for sort direction

[gervaisb]

Defining a sort parameter as an enum with - and + prefixes can break TypeScript clients. Enum values cannot start with those special characters and some generators sanitize those values by removing the unsupported prefixes. This lead to an enum with two identical values.

I agree that it is up to the generator to deal with those details. However, this can limit the usage of that pattern.

[pvdbosch]

The guide can't ensure compatibility with every generator, but we do try to make it compatible with the most commonly used ones. We should test if this also causes problems for others, especially openapi-generator; but don't know yet when I'll get around to this.

Some guides (like Zalando) use the same +/- sorting format, while others suffix the values with " asc" or " desc":

• https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md#96-sorting-collections
• https://github.com/NationalBankBelgium/REST-API-Design-Guide/wiki/Sorting-Example
• https://cloud.google.com/apis/design/design_patterns#sorting_order

We can also consider this format if it proves more compatible with tooling.

[gervaisb]

I fully agree with you. However, I thought it would be worst saying it.

I liked the ‘-‘ and ‘+’ prefixes. But after hitting this issue and searching for alternatives it appears that ´_desc’ and ´_asc’ is more explicit, and possibly more compatible than the other.

[pvdbosch]

Concern if spaces could cause problems (e.g. escaping when using curl). Flanders uses ":asc" and ":desc". Some use free string instead of explicit enum parameters.

&sort=name,-type &sort=name,type:desc

WIP guidelines around "greater than" etc use underscores.

WG decided to first test with openapi-generator before deciding to change the guide.

[pvdbosch]

WG status: alternatives not tested yet, needs work