Sorting

[nickevansuk]

Use Case

When returning information relating to sessions or facilities, there are several common sorts:

• Distance from location.geo
• startDate
• offers[0].price (low to high, high to low)

References

• sort=key1:asc,key2:desc,key3:asc - OpenStack
  • Extensible, and consistent with the filtering approach
• sort_by=-last_modified,+email - Moesif, Haufe-Lexware, Zalando
  • Lacks extensibility, as available sort orders are limited by characters
• sort=foo,bar desc - Google, Microsoft, OData
  • Extensible
• sort_by=desc(last_modified),asc(email) - Moesif
  • () pattern not used elsewhere
• sort=rating,reviews,name&desc=rating,reviews - Octo
  • Overall ordering of fields in sort not clear
• sort=date_of_birth|asc,zip_code|desc - PayPal
  • | character not used elsewhere

Proposal

As with filtering, the OpenStack approach appears to be the most user-friendly and explicit, as it strikes the best balance between extensibility and familiarity.

Example

• Distance from location.geo
  • sort=location.geo:nearest
• startDate
  • sort=startDate:asc
• orders[0].price (low to high, high to low)
  • sort=offers.price:asc (allows the implementation to flex to take intro account multiple offers and multiple currencies)
  • sort=offers.price:desc (allows the implementation to flex to take intro account multiple offers and multiple currencies)

[lukehesluke]

@nickevansuk considering the current state of https://github.com/openactive/opportunity-api/issues/1#issuecomment-406360624, it looks to me as if the only syntax that would be allowable within that grammar is:

• sort=subEvent.startDate,asc
• sort=location.geo,nearest
• sort=offers.price,desc

Something like sort[desc]=offers.price would be hard to describe for an API specification as the conditional that sort[desc] and sort[asc] cannot both be present in the query params. Requiring one and only one use of sort=, however, is easy to describe in e.g. OpenAPI/Swagger

[nickevansuk]

sort=offers.ext:publicAdultPrice,asc (see https://github.com/openactive/modelling-opportunity-data/issues/116) would solve the issue of how to sort Events with multiple Offers