The client asks for filters, sorting, pages and relationships with query parameters; you decide which ones are allowed with whitelists. The package reads them, validates them and applies them to the Eloquent query with four macros.
The four macros
| Eloquent builder macro | What it does |
|---|---|
jsonApiPaginate(?int $perPage = null, ?int $maxPerPage = null) | Fetches the page the client asked for (page[number], page[size]) and returns Laravel's paginator. A page out of range is an empty list. |
jsonApiSort(array $allowed, ?string $default = null) | Applies sort (- for descending) with a whitelist. It appends the primary key so pages are stable. It accepts ['author' => 'author_id'] to name a column differently. |
jsonApiFilter(exact: [], partial: [], scopes: []) | exact: equality (with commas, an IN). partial: LIKE %value% with % and _ escaped. scopes: calls a scope of the model. A name outside the lists is 400. |
jsonApiInclude(array $allowed) | Eager loads the relationships in include (['author', 'comments.author']; allowing a path allows its prefixes). A path outside the list is 400. |
The lists are written in snake_case (the columns and relationships of your model); the client sends them in the configured style.
When something is not allowed
A filter, a sort or an include that is not in your list answers 400 with the failing parameter in source. (code request.; see Errors). An unknown query parameter is ignored, unless you turn on reject_ in the configuration.
The page size
The page size is decided in this order, and it is always capped by the maximum:
- the client's (
page[size]); - the
jsonApiPaginate(perPage: 30)argument; - the middleware options (
->middleware('json-api.options:per_page=25,max_per_page=50')); - the configuration.
The already parsed query
$request->jsonApiQuery() gives the already parsed query, with includes(), fields(), sort(), filter() and page(), in case you need to read it yourself.