Sorting

Basic Sorting

To sort results, use the sort query parameter with the name of the field to sort by:

GET /users?sort=lastName

By default, sorting is in ascending order (A-Z, 0-9). To sort in descending order, add a minus sign (-) before the field name:

GET /products?sort=-price

Multi-Field Sorting

You can sort by multiple fields by separating them with commas. The order matters - results are sorted by the first field, then ties are broken by the second field, and so on:

GET /users?sort=role,lastName,firstName

You can mix ascending and descending sorts in a multi-field sort:

GET /products?sort=-category,name

This sorts products by category in descending order (Z-A), and within each category, sorts by name in ascending order (A-Z).

Sorting on Related Resources

You can sort based on fields in related resources using dot notation:

GET /posts?sort=author.lastName

This sorts posts by the last name of the author. You can go multiple levels deep:

GET /comments?sort=post.author.lastName

Sorting on Nested Fields

For resources with nested objects, you can sort by nested fields using dot notation:

GET /products?sort=specs.weight

This sorts products by the weight field within the specs object.

Sorting on Array Fields

When sorting on array fields, api.vision uses the first element of the array for comparison:

GET /products?sort=tags

For more advanced array sorting needs, consider using a custom field or scripting.

Sorting Null Values

By default, null values are sorted at the beginning for ascending sorts and at the end for descending sorts. You can control this behavior with the nulls parameter:

GET /users?sort=lastLogin&nulls=last

Options for the nulls parameter:

• first - null values appear first
• last - null values appear last

Sorting Types

api.vision automatically determines the appropriate sort method based on the field type:

Combining Sorting with Other Query Features

Sorting can be combined with filtering, pagination, and other query features:

GET /products?category=electronics&price_gte=100&sort=-rating,price&page=1&limit=20

This query:

1. Filters for electronics products with a price of 100 or more
2. Sorts by rating (descending) and then by price (ascending)
3. Returns the first page of results with 20 items per page

Advanced Example

GET /orders?
  status=shipped&
  sort=-orderDate,customer.lastName,customer.firstName&
  expand=customer,items&
  page=1&
  limit=10

This query fetches shipped orders, sorted first by order date (newest first), then by customer's last name, and finally by customer's first name. It includes the related customer and items, paginated to 10 items per page.