Order By

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:

Comma-separated list:

?order_by=field:asc,another_field:desc

Array-style query:

?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

Response:

[
  { "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

Explanation:

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.

Response:

[
  { "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.

Usage#

Sort Direction#

Sorting Behavior#

Examples#

Single Field Sorting#

Multiple Fields Sorting#

Array-style Query#

Error Handling#

Summary#