Sorting orders returned items by one or more fields and directions, helping consumers browse lists, render interfaces, and process data without rearranging results themselves. It matters especially for list and search operations that may contain many elements. section 8.6.3 section 9.6
Transaction search
A banking API can return large transactions first with GET /accounts/12345/transactions?sort=amount:desc. Multiple fields use comma-separated criteria: sort=date:desc,amount:asc orders recent transactions first, then smaller amounts. A useful default makes sort optional: omitting it can produce reverse-chronological results, equivalent to sort=date:desc. When a direction is omitted, ascending order is the default, so sort=date:desc,amount equals sort=date:desc,amount:asc. section 9.6.5
Design sorting as part of a consistent, consumer-friendly list operation:
- Keep the sort parameter optional and provide a helpful default ordering that matches common consumer needs. section 9.6.5
- Use the same parameter names, value syntax, directions, and conventions across comparable search operations; avoid switching between designs such as sort=balance:asc and order=balance,up. section 9.10.3
- Combine sorting with filtering and pagination so consumers can request only the relevant results, reducing transferred data and simplifying retrieval. section 9.6 section 9.11
- Document array ordering explicitly because JSON Schema cannot formally describe array order; use a schema description such as “sort the array by balance type: value-date and then expected.” section 8.6.3
Sorting is a design choice rather than a universal rule. Select fields and defaults according to the operation’s context, consumer needs, and complexity. Treat sorting as one part of a complete search recipe that also defines the resource path, query parameters, successful responses, errors, and no-result behavior. section 16.4.2 section 9.11
