Configuración · MundoProgra JSON:API

Todo se puede definir en el .env. Casi no hace falta tocar nada: los valores por defecto sirven para empezar.

Publicar el archivo

Para editar la configuración en el código en vez de en el .env (por ejemplo, para dar varios prefijos de ruta o una lista de except), publica el archivo:

php artisan vendor:publish --tag="json-api-config"

Queda en config/json-api.php. Los valores booleanos del .env aceptan true/false, 1/0, yes/no y on/off. Las listas (path_prefix como arreglo y except) solo se definen en el archivo.

La configuración se valida al arrancar: un valor inválido detiene la aplicación con un mensaje que lista todos los problemas a la vez, en lugar de fallar de a uno.

General

Opción	Variable en `.env`	Por defecto	Qué hace
`mode`	`JSON_API_MODE`	`prefix`	`prefix`: solo las rutas que empiezan con `path_prefix`. `global`: toda la aplicación responde en JSON:API (incluidos los `404` y los `500`)
`path_prefix`	`JSON_API_PATH_PREFIX`	`api`	Prefijo(s) de ruta cuando `mode` es `prefix`: un texto o un arreglo de textos
`except`	—	`['up']`	Rutas que el paquete nunca toca (admite comodines)
`strict_headers`	`JSON_API_STRICT_HEADERS`	`true`	Exige las cabeceras JSON:API (`Accept` y `Content-Type`); con `false` también acepta `application/json`
`member_case`	`JSON_API_MEMBER_CASE`	`camel`	Estilo de los nombres de atributos y relaciones, en la entrada y en la salida: `camel`, `kebab` o `snake`
`jsonapi_object`	`JSON_API_JSONAPI_OBJECT`	`true`	Incluye `{"jsonapi": {"version": "1.1"}}` en las respuestas
`allow_client_ids`	`JSON_API_ALLOW_CLIENT_IDS`	`false`	Con `false`, un `POST` con `data.id` responde `403`; con `true` se acepta el `id` que manda el cliente al crear
`allow_put`	`JSON_API_ALLOW_PUT`	`false`	También valida `PUT` como JSON:API (la especificación solo define `PATCH` para actualizar)
`reject_unknown_query_params`	`JSON_API_REJECT_UNKNOWN_QUERY_PARAMS`	`false`	Con `true`, un parámetro de consulta desconocido (de solo letras `a-z`) responde `400`; con `false` se ignora

Con strict_headers en true, que es el valor por defecto, un cliente que manda Accept: application/json (o text/html) dentro del alcance del paquete recibe un 406. Si migras una API que ya tiene clientes, JSON_API_STRICT_HEADERS=false te permite hacerlo de a poco.

Paginación

Opción	Variable en `.env`	Por defecto	Qué hace
`pagination.size`	`JSON_API_PAGE_SIZE`	`15`	Tamaño de página por defecto
`pagination.max_size`	`JSON_API_PAGE_MAX_SIZE`	`100`	Tope del `page[size]` que manda el cliente
`pagination.on_exceed`	`JSON_API_PAGE_ON_EXCEED`	`clamp`	Si el cliente pide más que `max_size`: `clamp` lo recorta al máximo, `error` responde `400`

Consulta y enlaces

Opción	Variable en `.env`	Por defecto	Qué hace
`query.max_include_depth`	`JSON_API_MAX_INCLUDE_DEPTH`	`3`	Profundidad máxima de `include` (por ejemplo, `author.comments.user` tiene profundidad 3)
`links.route_name_prefix`	`JSON_API_ROUTE_NAME_PREFIX`	vacío	Prefijo para resolver el nombre de las rutas al construir los `links`. Si la ruta no existe, el enlace se omite

Errores

Opción	Variable en `.env`	Por defecto	Qué hace
`errors.expose_details`	`JSON_API_EXPOSE_DETAILS`	`app.debug`	Muestra el detalle real de la excepción en los errores `500`. Sin valor, sigue a `app.debug`
`errors.include_code`	`JSON_API_INCLUDE_CODE`	`true`	Envía `code` en cada error; apagado significa nunca: ningún error lo lleva
`errors.code_prefix`	`JSON_API_CODE_PREFIX`	`mundoprogra.json-api`	Prefijo de los códigos por defecto del paquete. Vacío: sin prefijo
`errors.codes`	—	`[]`	Reemplaza códigos por los tuyos: la clave es el código base sin prefijo y el valor se usa tal cual, sin prefijo
`errors.include_id`	`JSON_API_INCLUDE_ID`	`false`	Agrega un `id` único a cada error y lo escribe también en el log, para encontrar una ocurrencia concreta

Por ejemplo, para reemplazar dos códigos por los tuyos:

'errors' => [
    'codes' => [
        'validation.required' => 'ERR-1001',
        'resource.not_found' => 'ERR-4040',
    ],
],

Los códigos base que puedes reemplazar están en la página de errores.