API Sorting Guidelines¶

Introduction¶

API sorting is an important feature for any API endpoint that returns a lot of data. If you're returning a list of users, your API users may want to sort by last modified date or by email.

API sorting provides flexibility to specify sorting order and supports sorting by one or more fields in a request.

API MAY provide sorting of collections in response [700]¶

A server MAY choose to support requests to sort resource collections according to one or more criteria ("sort fields").

An endpoint MAY support requests to sort the collections provided in the "primary data" with a sort query parameter.

An API can offer sorting also on single resources in the "primary data", but then sorting doesn't apply.

An API provider has the possibility to specify in the API specification, which fields are supported to sort the collection in the response. If the API restricts the sort functionality on dedicated fields (i.e. member of a resource), these "sort fields" MUST be documented in the API specification. The API client shall not identify the supported fields by try&error.

Parameter sort in request MUST specify sort fields [700.1]¶

The value for sort MUST represent sort fields.

The format of of the query parameter is:

GET /devices?sort=<expression>

The <expression> MUST contain the members to use for sorting and is on the right-hand side of the equal sign. The resource collection will be returned to the API client only if the sort query is feasible. (e.g. member exists)

Here is an example with sort field.

GET /devices?sort=age HTTP/1.1
Accept: application/json

API SHOULD support defining the sort order for each sort field individually [700.2]¶

Sort order MAY be defined by prefixing of member [700.2.1]¶

An API MAY support the customization of the sorting order. The API client MAY prefix the sort field with a minus (U+002D HYPHEN-MINUS, "-") for descending and plus (U+002B PLUS SIGN, "+") for ascending order.

Here is an example with a descending sort order.

GET /devices?sort=-created HTTP/1.1
Accept: application/json

The above example should return the newest devices first.

Here is an example with ascending sort order, that returns the oldest devices first.

GET /devices?sort=+created HTTP/1.1
Accept: application/json

The default sort order MUST be ascending as if a + is specified [700.2.2]¶

GET /devices?sort=age HTTP/1.1
Accept: application/json

The example demonstrates that the API client MAY not specify any sort order for member age. The default sort order MUST be ascending, as if the API client has specified plus (U+002B PLUS SIGN, "+") for ascending order.

API MAY support sorting by more than one sort field in one request [700.3]¶

An endpoint MAY support multiple sort fields by allowing comma-separated (U+002C COMMA, ",") sort fields. Sort fields MUST be applied in the order specified.

Here is an example with more than one sort field.

GET /devices?sort=age,name HTTP/1.1
Accept: application/json

The resulting collection sorts the resources first by age, oldest first. Among devices created at exactly the same time they will be sorted by name in the ascending order.

The sort request in turned order of the fields:

GET /devices?sort=name,age HTTP/1.1
Accept: application/json

The resulting collection sorts the resources first by name in ascending alphabetic order. Among devices sharing the same name they will be sorted by creation time in the ascending order, i.e. oldest first. As you see, the order in the sort query parameter is defining the sort behavior.

Sort order MUST be defined for each sort field individually [700.3.1]¶

You may prefix the sort field with a minus (U+002D HYPHEN-MINUS, "-") for descending and plus (U+002B PLUS SIGN, "+") for ascending order. The default behavior of ascending sort order in case of omitting the "-" or "+" applies in the same way for each field individually.

Here is an example with both descending and ascending sort order on two fields, demonstrating default ascending order for field name.

GET /devices?sort=-created,name HTTP/1.1
Accept: application/json

The above example should return the newest devices first. Among devices created at exactly the same time they will be sorted by name in the ascending order.