El paquete se activa solo al instalarlo. Esta página explica dónde actúa, qué agrega exactamente y cómo aplicarlo a una ruta suelta.
Dónde actúa
El alcance lo deciden tres opciones de la configuración:
| Opción | Efecto |
|---|---|
mode | prefix (por defecto): solo las rutas que empiezan con path_prefix. global: toda la aplicación, incluidos los 404 y los 500 |
path_prefix | El prefijo de ruta cuando mode es prefix (por defecto api): un texto o un arreglo de textos |
except | Rutas que el paquete nunca toca, en cualquier modo (por defecto ['up']); admite comodines |
Fuera de ese alcance el paquete no toca nada: una ruta como / responde como siempre, con su HTML. Dentro, todo sale en JSON:API, también los errores de una ruta que no existe.
Qué agrega
Dentro del alcance, el paquete agrega solo cuatro middleware al inicio de la pila global del kernel HTTP. Corren antes de buscar la ruta, y por eso cubren también las rutas que no existen, y antes que auth:
| Middleware | Qué hace |
|---|---|
json-api.apply | Marca la petición como JSON:API y arregla el Accept para que auth responda 401 en lugar de buscar la ruta login |
json-api.negotiate | Negocia el contenido: comprueba el Content-Type (415) y el Accept (406). El Content-Type se revisa solo si la petición trae cuerpo y su método es POST, PATCH o DELETE (PUT solo con allow_put) |
json-api.query | Valida los parámetros de consulta (400, con source.) |
json-api.document | Valida el documento del cuerpo (400 o 403, con source.) |
Para saber en qué orden se comprueba todo cuando una petición falla por más de un motivo, mira El orden de las comprobaciones.
No hace falta tocar bootstrap/app.php, Kernel ni Handler. Si tu bootstrap/app.php reemplaza la lista global con withMiddleware (Laravel 11 a 13), los middleware del paquete se agregan después y quedan al principio de la fila.
Una ruta suelta fuera del alcance
Si necesitas JSON:API en una ruta que queda fuera del alcance, aplica los cuatro middleware de una vez con json-api:
Route::get('reports/{report}', [ReportController::class, 'show'])->middleware('json-api');Los cuatro también existen por separado. Además hay json-api.options, que fija los límites de paginación de una ruta, por ejemplo json-api.options:per_page=25,max_per_page=50. Y json-api.document:relationship o json-api.document:resource fuerzan el tipo de documento sin mirar la URL.