El cliente pide filtros, orden, páginas y relaciones con parámetros de consulta; tú decides cuáles se permiten con listas blancas. El paquete los lee, los valida y los aplica a la consulta de Eloquent con cuatro macros.
Las cuatro macros
| Macro del constructor de Eloquent | Qué hace |
|---|---|
jsonApiPaginate(?int $perPage = null, ?int $maxPerPage = null) | Trae la página que pidió el cliente (page[number], page[size]) y devuelve el paginador de Laravel. Una página fuera de rango es una lista vacía. |
jsonApiSort(array $allowed, ?string $default = null) | Aplica sort (- para descendente) con una lista blanca. Agrega la clave primaria para que las páginas sean estables. Acepta ['author' => 'author_id'] para nombrar de otra forma una columna. |
jsonApiFilter(exact: [], partial: [], scopes: []) | exact: igualdad (con comas, un IN). partial: LIKE %valor% con % y _ escapados. scopes: llama a un scope del modelo. Un nombre fuera de las listas es 400. |
jsonApiInclude(array $allowed) | Carga por anticipado las relaciones de include (['author', 'comments.author']; pedir una ruta permite sus prefijos). Una ruta fuera de la lista es 400. |
Las listas se escriben en snake_case (las columnas y relaciones de tu modelo); el cliente las manda en el estilo configurado.
Cuando algo no está permitido
Un filtro, un orden o un include que no está en tu lista responde 400 con el parámetro que falla en source. (código request.; mira Errores). Un parámetro de consulta desconocido se ignora, salvo que actives reject_ en la configuración.
El tamaño de página
El tamaño de página se decide en este orden, y siempre queda acotado por el máximo:
- el del cliente (
page[size]); - el argumento
jsonApiPaginate(perPage: 30); - las opciones del middleware (
->middleware('json-api.options:per_page=25,max_per_page=50')); - la configuración.
La consulta ya analizada
$request->jsonApiQuery() entrega la consulta ya analizada, con includes(), fields(), sort(), filter() y page(), por si necesitas leerla tú mismo.