Sorting (#132)

Sorting

When retrieving a list of resources, an ordered list of items is easier to understand and logically process. It helps the user comprehend and utilize the results in a more meaningful way.

When used in conjunction with filtering, sorting a list of resources allows the user to process the results without additional analysis.

Guidance

List APIs must provide a default sort order. Multiple requests to retrieve the same list must results in the same ordering of items.

List APIs should provide sorting abilities in the form of a ?sort= query parameter.

If sorting is supported, the list of sortable attributes must be a superset of the filterable attributes. The list of sortable attributes should be provided in the attribute description.

If sorting is supported, the sort parameter should support sorting by one or more attributes at the same time.

Default Sort Order

The default sort order should be defined in the most commonly helpful way to the end user based on the context of the resource. For example, the default order may be a logical primary attribute such as:

• the name in ascending order
• the created date in ascending order
• the updated date in descending order
• the [most impactful] in descending order

The default sort order does not have to be documented and is not considered a binding contract. It may be changed without notice.

Order by UUID as the default sort order should be avoided.

Syntax and Behavior

To sort a list request, the ?sort= query parameter is used where the value is a comma-delimited list of attributes to sort on.

?sort=foo,bar desc,foo.baz asc

• The default sort order is ascending. The asc suffix (with a space delimiter) should be optionally accepted.
• To specify a descending order, a desc suffix (with a space delimiter) to the attribute. (eg: bar desc)
• Multiple sort attributes may be provided via a comma separated list from left to right.
• Redundant space characters are insignificant. (eg: foo , bar desc == foo,bar desc)
• JSONPath notation may be used to specify a sub-attribute. (eg: foo.bar is for {foo:{bar:value}})
• Determination of the sort order should be predictable "best-effort". (eg: Sorting on UTF-8 characters)

If the sort query cannot be fully executed, then the API should return a 400 bad request error.

Limitation

The syntax of sorting AIP deviates from the syntax of the filtering AIP which does not make for a consistent use of delimiters across the two standards. Sorting uses spaces and commas while filtering uses square brackets. The reason for this limitation is because the ordering of query parameters must have no impact on the actual response. Ordering does not matter in filtering but it does matter for sort. No consistent proposals for sorting with square brackets were found.