Download the PHP package intermax/laravel-json-api without Composer

Laravel JSON:API

Laravel API is a package to quickly build an API according to the JSON:API specification. It also generates OpenAPI documentation on the fly based on your API endpoints.

• Installation
• Configuration
• Basic usage
• Query Parameters
  • CollectionRequest
  • Controller
  • Filter types
• MutationRequest
• OpenAPI generation

Installation

Configuration

To render exceptions in JSON:API format, you can add the middleware Intermax\LaravelJsonApi\Middleware\RenderJsonApiExceptions to applicable routes. A sensible example would be in the HTTP Kernel in the API middleware group:

Basic Usage

To create an endpoint you just create a Laravel route like you're used to doing. After that you need to create a resource. Let's assume we make an endpoint that returns a UserResource:

After that you should create your controller method. Generally you would want an API Resource Controller. If you return the resource you just made your first endpoint with the Laravel API package:

❗ TIP: Make sure to type hint your resource on the controller method so Open API docs can be generated correctly. Read more about this at Open API generation

Query Parameters

You might want ways to apply filters, sorts and includes to your requests. With JSON:API this is done by applying a filter, sort and include variables to the query string:

CollectionRequest

With this package you can configure some predefined filters or add your own. You can also add includes and sorts. To do this you can add a CollectionRequest to your controller method. Essentially this is an extended FormRequest. Your custom CollectionRequest needs to extend the Intermax\LaravelJsonApi\Requests\CollectionRequest. It might look like this:

This specific CollectionRequest adds two filters, filter[createdAt] and filter[isAdmin]. To see how these specific filters work, see filter types.

Controller

To make the filters, includes and sorts actually do their magic, we need a little more. In the controller the QueryResolver needs to be used to apply the filters to the Eloquent query. Under the hood this uses the laravel-query-builder package from spatie.

Filter Types

This package provides two types of filters out of the box. One is the ScopeFilter. Like its name implies this will call the scope with the value that's being sent.

The second one is called the OperatorFilter. It allows you to query with a set of operators:

• Equals: filter[column]=value or filter[column][eq]=value
• Not equals: filter[column][nq]=value
• Greater than: filter[column][gt]=value
• Less than: filter[column][lt]=value
• Greater than or equals: filter[column][gte]=value
• Less than or equals: filter[column][lte]=value
• Contains: filter[column][contains]=value

Allowed operators can be specified (default all are allowed):

Mutation Requests

For POST, PUT or PATCH requests this package provides an extendable base request for convenience. Instead of a regular FormRequest you know from Laravel it should extend the MutationRequest. This class helps you to adhere to the JSON:API specification for your requests:

• It rejects requests without the correct content type (application/vnd.api+json)
• The implementing class can provide rules for the attributes and relationships fields
• It has methods to retrieve validatedAttributes and validatedRelationships

⚠️ WARNING: Be aware that if you were previously not checking for the content type you could easily create a breaking change in your application.

Usage

An example implementation may look like this:

And in the controller you can use the methods to retrieve validated fields:

OpenAPI Generation

This package leverages the Laravel Open API package to provide a /docs endpoint (and /docs/json and /docs/yaml endpoints).

The open API package will scan for api routes, read FormRequests, determine ApiResources and try to guess the output of the resource. We aim to generate as much documentation as possible with a minimal amount of configuration.

There are a couple of things that need to be in place for this to work best:

• Use the CollectionRequest for 'collection-type' endpoints, even if you don't use Eloquent it will still be able to infer the query parameters. You can even validate query parameters with rules.
• Typehint the resource you want to return in your controller method.
• Use FormRequest validation for your POST/PUT/PATCH endpoints and include all fields in it (even if they have no validation). The package uses this to determine the request body.
• The package will get all your fields/attributes from the resource array.

Improving resource attribute data types

If you look at the docs and see all your resource attributes are listed as string in the array, there is one more thing you can do to improve it. Wrap every field in a Intermax\LaravelOpenApi\Generator\Values\Value type object: