Configuration · MundoProgra JSON:API

Everything can be set in .env. You hardly need to touch anything: the defaults are enough to get started.

Publishing the file

To edit the configuration in code instead of in .env (for example, to give several route prefixes or an except list), publish the file:

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

It ends up in config/json-api.php. Boolean values in .env accept true/false, 1/0, yes/no and on/off. Lists (path_prefix as an array and except) can only be set in the file.

The configuration is validated at boot: an invalid value stops the application with a message that lists all the problems at once, instead of failing one at a time.

General

Option	`.env` variable	Default	What it does
`mode`	`JSON_API_MODE`	`prefix`	`prefix`: only routes that start with `path_prefix`. `global`: the whole application responds in JSON:API (`404` and `500` included)
`path_prefix`	`JSON_API_PATH_PREFIX`	`api`	Route prefix(es) when `mode` is `prefix`: a string or an array of strings
`except`	—	`['up']`	Routes the package never touches (wildcards allowed)
`strict_headers`	`JSON_API_STRICT_HEADERS`	`true`	Requires the JSON:API headers (`Accept` and `Content-Type`); with `false` it also accepts `application/json`
`member_case`	`JSON_API_MEMBER_CASE`	`camel`	Naming style of attributes and relationships, for input and output: `camel`, `kebab` or `snake`
`jsonapi_object`	`JSON_API_JSONAPI_OBJECT`	`true`	Includes `{"jsonapi": {"version": "1.1"}}` in responses
`allow_client_ids`	`JSON_API_ALLOW_CLIENT_IDS`	`false`	With `false`, a `POST` with `data.id` responds `403`; with `true` the `id` sent by the client is accepted when creating
`allow_put`	`JSON_API_ALLOW_PUT`	`false`	Also validates `PUT` as JSON:API (the specification only defines `PATCH` for updates)
`reject_unknown_query_params`	`JSON_API_REJECT_UNKNOWN_QUERY_PARAMS`	`false`	With `true`, an unknown query parameter (of only `a-z` letters) responds `400`; with `false` it is ignored

With strict_headers set to true, which is the default, a client that sends Accept: application/json (or text/html) inside the package scope gets a 406. If you are migrating an API that already has clients, JSON_API_STRICT_HEADERS=false lets you do it gradually.

Pagination

Option	`.env` variable	Default	What it does
`pagination.size`	`JSON_API_PAGE_SIZE`	`15`	Default page size
`pagination.max_size`	`JSON_API_PAGE_MAX_SIZE`	`100`	Upper limit for the `page[size]` the client sends
`pagination.on_exceed`	`JSON_API_PAGE_ON_EXCEED`	`clamp`	If the client asks for more than `max_size`: `clamp` trims it to the maximum, `error` responds `400`

Query and links

Option	`.env` variable	Default	What it does
`query.max_include_depth`	`JSON_API_MAX_INCLUDE_DEPTH`	`3`	Maximum `include` depth (for example, `author.comments.user` has depth 3)
`links.route_name_prefix`	`JSON_API_ROUTE_NAME_PREFIX`	empty	Prefix used to resolve route names when building `links`. If the route does not exist, the link is omitted

Errors

Option	`.env` variable	Default	What it does
`errors.expose_details`	`JSON_API_EXPOSE_DETAILS`	`app.debug`	Shows the real exception detail in `500` errors. Without a value, it follows `app.debug`
`errors.include_code`	`JSON_API_INCLUDE_CODE`	`true`	Sends `code` in every error; off means never: no error carries it
`errors.code_prefix`	`JSON_API_CODE_PREFIX`	`mundoprogra.json-api`	Prefix of the package default codes. Empty: no prefix
`errors.codes`	—	`[]`	Replaces codes with your own: the key is the base code without prefix and the value is used as is, without prefix
`errors.include_id`	`JSON_API_INCLUDE_ID`	`false`	Adds a unique `id` to every error and also writes it to the log, to find one specific occurrence

For example, to replace two codes with your own:

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

The base codes you can replace are on the errors page.