Skip to main content

Pagination

A list that answers with every row grows with the table until one request reads it all. A list that pages by number skips or repeats rows when one is added or removed between two pages. With a cursor, each page names where the next one starts: a client asks for page[size] items, follows links.next and links.prev, and never sees a page number. A size is bounded, so no single request reads more than the largest page.

Page a list​

Hand the query of the list and the request to CursorPages, and the page it gives to JsonApiResource::collection(). Laravel resolves CursorPages for the route:

use App\Models\Order;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\JsonApi\JsonApiResource;
use Illuminate\Support\Facades\Route;
use Pushery\HttpApi\Pagination\CursorPages;

Route::get('/orders', function (Request $request, CursorPages $pages) {
return JsonApiResource::collection($pages->of(Order::query()->latest(), $request));
})->middleware('auth:sanctum');

The first page, and the one its links.next leads to:

GET /api/orders?page[size]=2 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
"data": [
{"type": "orders", "id": "1044", "attributes": {"note": "Leave at the door"}},
{"type": "orders", "id": "1043", "attributes": {"note": null}}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": "https://api.shop.example/api/orders?page%5Bsize%5D=2&page%5Bcursor%5D=eyJjcmVhdGVkX2F0Ij..."
}
}

What the request names​

ParameterTakesWithout it
page[size]a whole number from 1 to http-api.pagination.max_size, 100 by defaulthttp-api.pagination.size items, 20 by default
page[cursor]the cursor of a links.next or links.prev of the same listthe first page

A size outside that range and a cursor that is not one of the list's are refused with 400 malformed_request, a JSON:API error that names the parameter in source.parameter, and never answered with a first page the client did not ask for. A cursor of another list, one sorted by other columns, is refused the same way.

The links keep every other parameter of the request: a filter, a sorting and page[size] reach the next page as they reached this one. They carry the name the request came in under, so behind a gateway or a load balancer, the application trusts that proxy and its forwarded headers, as Laravel's TrustProxies middleware sets it up, and the links name the public host and scheme.

Filter, sort and include​

A list takes only the filters, sorts and includes its route declares. Declare them with spatie/laravel-query-builder, which the application requires itself, and hand its Eloquent builder to CursorPages:

use App\Models\Order;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\JsonApi\JsonApiResource;
use Illuminate\Support\Facades\Route;
use Pushery\HttpApi\Pagination\CursorPages;
use Spatie\QueryBuilder\AllowedFilter;
use Spatie\QueryBuilder\QueryBuilder;

Route::get('/orders', function (Request $request, CursorPages $pages) {
$orders = QueryBuilder::for(Order::class, $request)
->allowedFilters(AllowedFilter::exact('status'))
->allowedSorts('created_at')
->allowedIncludes('lines')
->getEloquentBuilder();

return JsonApiResource::collection($pages->of($orders, $request));
})->middleware('auth:sanctum');

A filter, a sort, an include, a field or an append the route does not declare is refused with 400 malformed_request, one JSON:API error for each parameter the refusal names in source.parameter: filter[color], sort, include, fields[orders] or append. The query builder's own message, which lists what the route allows, never reaches the client. The depth of an include is the depth the route declares, so lines.product is refused until the route names it; declare two levels at most.

The order of a list​

The query orders the list, and CursorPages orders it by the model's key last, unless the query orders by the key already. Without the key, two rows with the same value in every sort column have no order between them, and the cursor would skip or repeat one at the edge of a page. Sort by columns, not by an expression: a cursor holds the values of the columns the list is sorted by.

The pages come from Laravel's cursor paginator, part of every Laravel application as the component illuminate/pagination.