Pagination, filtering, and sorting

Pagination, filtering and sorting

Pagination

Page pagination

Use page and limit:

GET /users?page=2&limit=50

Example response snippet:

{
  "pagination": {
    "page": 2,
    "page_size": 50,
    "has_more": true,
    "total_pages": 10
  }
}

Offset pagination

Use offset and limit:

GET /users?offset=100&limit=50

Example response snippet:

{
  "pagination": {
    "offset": 100,
    "limit": 50,
    "has_more": true,
    "total": 500
  }
}

Cursor pagination

GET /users?cursor=base64EncodedCursor&limit=100

Example response snippet:

{
  "pagination": {
    "limit": 100,
    "current_cursor": "base64EncodedCursor",
    "next_cursor": "anotherBase64EncodedCursor",
    "has_more": true
  }
}

Sorting

Use ’+’ (ASC) or ’-’ (DESC) as a prefix for each field. If not specified, default is ASC. Multiple fields can be separated by a comma.

GET /users?order_by=+id,-price

In Apivalk, this order_by parameter automatically populates the sorting() bag on the request object, based on the fields allowed in the Route definition. Any field not declared via Route::sorting([...]) (or AbstractResource::availableSortings()) is rejected by the validation middleware with a 422.

Filtering

Filtering allows clients to narrow down results by specifying conditions on fields. A field carries the operator in brackets, so one field can take several conditions at once. Example: retrieve all plugs with phase AC:

GET /plugs?phase[eq]=AC

Example: a price range on a single field, rather than two invented field names:

GET /orders?price[gte]=200&price[lte]=500

Where a field accepts a single operator, the flat form is the shorter equivalent:

GET /plugs?phase=AC

Getting started

Concepts

HTTP

Resources

Routing

Cache

Middleware

Documentation (OpenAPI)

Core System

Security

Customization

How-To Guides

API Standards

Pagination, filtering, and sorting

Sorting

Filtering

​Pagination, filtering, and sorting