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 using flat key-value parameters. Example: retrieve all plugs with phase AC:

GET /plugs?phase=AC

Filters may also use parameter names that are not directly bound to object fields. Example:

GET /orders?min_price=200

​Pagination, filtering, and sorting