SAS REST APIs: Sorting

When invoking a query on an orderable collection, the client often requires the data in a sorted order for presentation to the user. Sort criteria are specified by the sortBy query parameter. 

  GET https://www.example.com/reports/reports?sortBy=name,description
This call results in a paginated collection view that is sorted first by the report name, then by the description.

The value of the sortBy parameter is one or more sort criteria, separated by commas. Sort criteria consist of a key which is a member of a resource. Each sort criteria may also have sort options which specify sort order or collation strength. Note: Not all APIs support collation strength options. (The values may be specified in the sortBy parameter but are not honored by the underlying service.)

sortBy syntax

The syntax of of the sortBy sort criteria is defined by the following Backus–Naur form syntax: 

sortCriteria ::= criteria [ ',' sortCriteria ]
criteria ::= key [ ':' options ]
options ::= option [ ':' options ]
option ::= 'ascending' | 'descending'
option ::= 'primary' | 'secondary' | 'tertiary' | 'quaternary' | 'identical'

The key is the name of a member (also known as a field) in the resources that are being sorted. For example, if a collection resource /someApi/models contains a collection of models, and each model has members with names model, type, modifiedTimeStamp and modifiedBy, a client can request the collection of models sorted first by modified date (most recent first), then who last modified the resource, then by type, then by name: 

  GET https://www.example.com/someApi/models?sortBy=modifiedTimeStamp:descending,modifiedBy,type,name
If more than one criteria exist, they are considered subgroup sorting criteria. The order is important: the second sort criteria, if present, applies to items that are equal according to the first sort criteria, and so on. It is unlikely that many resources will have the same modifiedTimeStamp. For the query 

  GET https://www.example.com/someApi/models?sortBy=modifiedBy,type,modifiedTimeStamp:descending

there are likely to be several models modified by each user, and for each user, several models with the same type. Within those subgroups, the items will be sorted by descending modified timestamp.

sortBy sort criteria options

Ordering options are:

ascending
sort in ascending order; this is the default order default if descending is omitted
descending
sort in descending order
primary 
Typically, this is used to denote differences between base characters (for example, "a" < "b", "a" == "A"). It is the strongest difference. For example, dictionaries are divided into different sections by base character. Case is ignored.
secondary 
Accents in the characters are considered differences (for example, "as" < "às" < "at", , "at" == "At"). Other differences between letters can also be considered secondary differences, depending on the language. A secondary difference is ignored when there is a primary difference anywhere in the strings. Case is ignored.
tertiary 
Upper and lower case differences in characters are distinguished at tertiary strength (for example, "ao" < "Ao" < "aò"). In addition, a variant of a letter differs from the base form on the tertiary strength (such as "A" and "Ⓐ"). Another example is the difference between large and small Kana. A tertiary difference is ignored when there is a primary or secondary difference anywhere in the strings.
quaternary 
When punctuation is ignored at primary to tertiary strength, an additional strength level can be used to distinguish words with and without punctuation (for example, "ab" < "a-b" < "aB").
identical
When all other strengths are equal, the identical strength is used as a tiebreaker. The Unicode code point values of the NFD form of each string are compared, just in case there is no difference. For example, Hebrew cantillation marks are only distinguished at strength. This strength should be used sparingly, as only code point value differences between two strings is an extremely rare occurrence. Using this strength substantially decreases the performance for both comparison and collation key generation APIs.

If more than one of {ascending,descending} appear, the last occurrence is used. If more than one of {primary,secondary,tertiary,identical} appear, the last occurrence is used. The default sorting strength is tertiary.

Consult the documentation for each API to determine the default sort order for its orderable collections. If it is not documented, you can assume the collection order is not guaranteed and the service MAY return items in a different order in future requests. For pagination, the first, next, prev, and last link relations, if present, preserve the sortBy query parameter if it was used. For pagination, the start query parameters are relative to sorted collection indexes.

The sort keys are selected from the full set of fields in the collection's underlying resource, which may be a superset of the fields in the requested representation on any specific query.