Skip to content

Specifying sort order direction in a JSON API

Does Restful API define proper ways to give Sort Order Direction, (Ascending or Descending) for API user parameters ?

I am letting a user input a request string, that only allows two options for API to work “Ascending” or “Descending” . Is there a more formal way of doing this per standards?


  "sortField": "PaymentDate",
  "sortOrder": "Descending"

Specifying sort order in a JSON API



The JSON:API specification specifies that sorting order is ascending by default. Client could switch the sorting order by prefixing the sort field with a minus (-).

The sort order for each sort field MUST be ascending unless it is prefixed with a minus (U+002D HYPHEN-MINUS, “-“), in which case it MUST be descending.

Your example given does not look as if your API implements the JSON:API specification. Even though this question is tagged with [json-api]. If you API does not implement the JSON:API specification, you are free to design the API for controlling sorting order as you like.

The API specification of the OpenStack project could give an inspiration. It also uses a comma-separated list of sorting fields: ?sort=key1,key2,key3. A client may specify the sorting direction by appending either asc or desc to the sorting field using colon (:) as a separator: ?sort=key1:asc,key2:desc,key3:asc. If sorting direction is not specified, then the server can chose sorting direction.

Sorting is determined through the use of the ‘sort’ query string parameter. The value of this parameter is a comma-separated list of sort keys. Sort directions can optionally be appended to each sort key, separated by the ‘:’ character.

The supported sort directions are either ‘asc’ for ascending or ‘desc’ for descending.

The caller may (but is not required to) specify a sort direction for each key. If a sort direction is not specified for a key, then a default is set by the server.