The order_by
query parameter allows clients to customize the sorting of resources in the API response. By specifying fields and sort directions, you can control the order in which results are returned. This feature is especially useful for creating ordered views or paginated responses.Usage#
The order_by
parameter supports two formats:1.
?order_by=field:asc,another_field:desc
2.
?order_by[]=field:asc&order_by[]=another_field:desc
Sort Direction#
For each field, the sort direction can be specified as:asc
for ascending order (default)
desc
for descending order
Sorting Behavior#
Sorting by multiple fields follows the order they are provided. If two or more records have the same value for the first field, the API will use the next field in the list to resolve the tie.Examples#
Single Field Sorting#
To sort by a single field in ascending order:GET /api/resource?order_by=name:asc
[
{ "id": 1, "name": "Alice" },
{ "id": 2, "name": "Bob" }
]
Multiple Fields Sorting#
To sort by multiple fields:GET /api/resource?order_by=name:asc,description:desc
Records are first sorted by name
in ascending order.
If two records have the same name
, they are further sorted by description
in descending order.
[
{ "id": 1, "name": "Alice", "description": "Zebra" },
{ "id": 2, "name": "Alice", "description": "Apple" },
{ "id": 3, "name": "Bob", "description": "Monkey" }
]
Array-style Query#
You can also specify the sorting fields as an array:GET /api/resource?order_by[]=name:asc&order_by[]=description:desc
This will produce the same result as the comma-separated example above.Error Handling#
If an invalid field or direction is provided, the API will return a 400 Bad Request
response with an error message detailing the issue.Summary#
Use order_by
to control the sorting of API responses.
Specify fields and directions in either a comma-separated list or an array-style query.
Sorting is applied in the order fields are listed, resolving ties progressively.
By leveraging the order_by
parameter, you can efficiently organize API responses to suit your application needs. Modified at 2025-05-13 05:24:11