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
| Parameter | Takes | Without it |
|---|---|---|
page[size] | a whole number from 1 to http-api.pagination.max_size, 100 by default | http-api.pagination.size items, 20 by default |
page[cursor] | the cursor of a links.next or links.prev of the same list | the 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.