Add jsonapi.org compliant APIs to your Laravel 5 application. Based on the framework agnostic packages neomerx/json-api and cloudcreativity/json-api.
From jsonapi.org
If you've ever argued with your team about the way your JSON responses should be formatted, JSON API is your anti-bikeshedding weapon.
By following shared conventions, you can increase productivity, take advantage of generalized tooling, and focus on what matters: your application. Clients built around JSON API are able to take advantage of its features around efficiently caching responses, sometimes eliminating network requests entirely.
For full information on the spec, plus examples, see http://jsonapi.org
- Encoding of JSON API responses using the
neomerx/json-apipackage. - Start JSON API support on route groups through a single piece of middleware, which automatically checks request headers and loads JSON API query parameters.
- Registration of JSON API defined resource end-points via a simple route helper.
- Define supported JSON API extensions via middleware (on route groups or individual controllers).
- A JSON API controller providers helpers to:
- Automatically check request query parameters.
- Decode request body content into objects with a standard, fluent, interface. Makes handling content easier.
- Validate request body content as it is being decoded, including using Laravel validates on resource object attributes.
- Helpers for sending common JSON API responses, that automatically include requested encoding parameters, the encoded media type plus registered supported extensions.
- Rendering of exceptions into JSON API error responses, plus easy sending of error responses via throwable JSON API error objects.
- Configuration settings - including schemas, encoders, decoders and exception rendering - all defined in a configuration file in your Laravel application.
Install using Composer:
$ composer require cloudcreativity/laravel-json-apiAdd the package service provider to your config/app.php providers array. It is important that it is added before your application's route service provider.
\CloudCreativity\JsonApi\ServiceProvider::classPlus add the following to the list of aliases in the same file (config/app.php) so that you can use the JsonApi facade:
'aliases' => [
// ... existing aliases
'JsonApi' => CloudCreativity\JsonApi\Facade::class
]Then publish the package config file:
$ php artisan vendor:publish --provider="CloudCreativity\JsonApi\ServiceProvider"Configuration settings are describe in the usage section below.
- Configuration keys are stored in constants on the
CloudCreativity\JsonApi\Configclass (and will be referred to asC::below). - Middleware names are stored in the
CloudCreativity\JsonApi\Middlewareclass (and will be referred to asM::below). This class also has some static methods for easily constructing middleware names with middleware options.
To define JSON API endpoints, the M::JSON_API middleware must be used. This is easily done by using route groups, for example:
Route::group(['middleware' => M::JSON_API], function () {
// define JSON-API routes here.
});If every route in your application is a JSON API endpoint, then you can set the C::IS_GLOBAL option to true. This will install the same piece of middleware on the HTTP Kernel, so that it is invoked for every request.
The JSON API spec defines the endpoints that should exist for each resource object type, and the HTTP methods that relate to these. Defining resource object endpoints is as easy as:
Route::group(['middleware' => M::JSON_API], function () {
JsonApi::resource('articles', 'Api\ArticlesController', [
'hasOne' => ['author'],
'hasMany' => ['comments'],
]);
JsonApi::resource('people', 'Api\PeopleController');
});Per resource type, the following endpoints will be registered (using the articles resource type in the example above):
| URL | HTTP Method | Controller Method |
|---|---|---|
| /articles | GET | index() |
| /articles | POST | create() |
| /articles/:id | GET | read($id) |
| /articles/:id | PATCH | update($id) |
| /articles/:id | DELETE | delete($id) |
| /articles/:id/author | GET | readAuthor($id) |
| /articles/:id/relationships/author | GET | readAuthorRelationship($id) |
| /articles/:id/relationships/author | PATCH | updateAuthorRelationship($id) |
| /articles/:id/comments | GET | readComments($id) |
| /articles/:id/relationships/comments | GET | readCommentsRelationship($id) |
| /articles/:id/relationships/comments | PATCH | updateCommentsRelationship($id) |
| /articles/:id/relationships/comments | DELETE | deleteCommentsRelationship($id) |
You do not need to implement all these methods if extending this package's Http\Controllers\JsonApiController. The controller is configured to send a 501 Not Implemented response for any missing methods.
The M::JSON_API middleware effectively boots JSON API support for the routes on which it is applied. As part of this boot process it:
- Creates a
CodecMatcherInterfacefrom your configuration. - Creates a
ParametersInterfacefrom the received request. - Checks that the request headers match to an encoder in the codec matcher.
- Parses the request query parameters.
If the checks pass, then the codec matcher instance and parameters instances are registered on the JsonApi service. These can be accessed through the JsonApi facade:
JsonApi::getCodecMatcher()returns aNeomerx\JsonApi\Contracts\Codec\CodecMatcherInterfaceinstance.JsonApi::getParameters()returns aNeomerx\JsonApi\Contracts\Parameters\ParametersInterfaceinstance.
Exceptions will be thrown if the checks do not pass.
If at any point you need to check whether the middleware was run (i.e. whether you're currently in a JsonApi route), then use the JsonApi::isActive() method.
To register supported extensions, use the M::SUPPORTED_EXT middleware. This takes middleware parameters that list the extensions supported. A static method M::ext() allows the middleware name to be easily composed. For example:
Route::group([
'middleware' => [M::JSON_API, M::ext('ext1', 'ext2')]
], function () {
// JSON API routes here, all supporting the above extensions.
});Middleware makes it easy to register multiple routes (or even an entire API) that support the same extensions. Alternatively, you can use the supported extension middleware as controller middleware if desired.
JSON API support in controllers can be added by extending CloudCreativity\JsonApi\Http\Controllers\JsonApiController. This has a number of helper methods to assist in handling JSON API requests and sending responses.
Each of the following pieces of functionality are implemented using traits. So if you want to include any of the functionality in your own custom controllers, just include the relevant trait. The traits are in the same namespace as the JsonApiController.
The JsonApiController will automatically check the query parameters before your controller action method is invoked. To define what query parameters your controller allows, set the properties that are defined in the QueryCheckerTrait.
This automatic checking means that by the time your controller action method is invoked, the request headers and query parameters have all been checked. Your action method can get the query parameters by calling $this->getParameters().
If you want to disable automatic checking of query parameters before your controller methods are invoked, then set the $autoCheckQueryParameters property of your controller to false.
Note that if you are adding the trait to your own custom controller, you will need to call $this->checkParameters() to trigger the checking of parameters.
To decode the request content body with the decoder that matched the request Content-Type header, then call $this->getContentBody().
If you want to use a CloudCreativity\JsonApi\Contracts\Object\DocumentInterface object to handle the request content in your controller action, use $this->getDocumentObject(). This method ensures the decoder has returned a DocumentInterface object, or if it has returned a stdClass object it will be cast to a DocumentInterface object.
Shorthands are also provided if you are expecting the document to contain a resource object in its data member, or if the provided document represents a relationship. Use $this->getResourceObject() and $this->getRelationshipObject() respectively.
These helper methods are implemented in the DocumentDecoderTrait.
If desired, you can validate the body content as it is decoded. All of the content body getter methods accept an optional validator that is applied when the document content is decoded. All of methods for getting the request body content take an optional validator argument.
If the received content is a resource object, you can use the $this->getResourceObjectValidator() method. For example:
class ArticlesController extends JsonApiController
{
// ...
public function update($id)
{
$validator = $this
->getResourceObjectValidator(
// the expected resource type
'articles',
// the expected id (use null for new resources)
$id,
// the rules for the attributes - uses the Laravel validation implementation.
[
'title' => 'string|max:250',
'content' => 'string',
'draft' => 'boolean',
],
// Laravel validation messages, if you need to customise them
[],
// whether the attributes member must be present in the resource object
true
);
$object = $this->getResourceObject($validator);
// ...
}
}The validator returned by $this->getResourceObjectValidator() provides helper methods for also defining relationship validation rules.
For relationship endpoints, you can get a validator for the relationship provided using one of the following helper methods:
class ArticlesController extends JsonApiController
{
// ...
public function updateAuthorRelationship($id)
{
$validator = $this->getHasOneValidator('person');
$relationship = $this->getRelationshipObject($validator);
// ...
}
public function updateCommentsRelationship($id)
{
$validator = $this->getHasManyValidator('comments');
$relationship = $this->getRelationshipObject($validator);
// ...
}
}These helper methods are provided by the DocumentValidatorTrait, which uses the DocumentDecoderTrait.
The class CloudCreativity\JsonApi\Http\Responses\ResponsesHelper provides a number of methods for constructing JSON API responses. This helper automatically uses request encoding parameters, the matched encoding media type plus any registered supported extensions.
If you have extended the JsonApiController, you can use this helper by calling $this->reply() then the method for the type of response you want to send. For example, to send a content response:
class ArticlesController extends JsonApiController
{
// ...
public function read($id)
{
$article = Article::find($id);
if (!$article) {
$this->notFound();
}
return $this
->reply()
->content($article);
}
}The available helpers are:
| Method | Detail |
|---|---|
statusCode |
Send a status code only reply |
noContent |
Send a no content reply (204) |
meta |
Send meta only |
content |
Send content (resource object, null, or collection) |
created |
Send a resource created response (encoded object, location header and 201 status |
relationship |
Send a relationship response (encoded identifier, null, or collection of identifiers) |
See the class for the parameters that each helper method accepts.
The reply method is added to the controller via the ReplyTrait.
To add JSON API support to your application's Exception Handler, add the Exceptions\HandlerTrait to your App\Exceptions\Handler instance. Then, in your render() method you can do the following:
namespace App\Exceptions;
use CloudCreativity\JsonApi\Exceptions\HandlerTrait;
use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
class Handler extends ExceptionHandler
{
use HandlerTrait;
// ...
public function render($request, \Exception $e)
{
if ($this->isJsonApi()) {
return $this->renderJsonApi($request, \Exception $e);
}
// do standard exception rendering here...
}
}You can configure the exception renderer in your json-api config file under the C::EXCEPTIONS key. This takes a default HTTP status (which is 500 if not provided) plus a map of exceptions. The map should be an array of Exception class names as keys, with their values either being an HTTP status code or an array representing the JSON API Error object to return. For example:
use CloudCreativty\JsonApi\Exceptions\StandardRenderer as Renderer;
use CloudCreativity\JsonApi\Contracts\Error\ErrorObjectInterface as Error;
[
// ... other config
C::EXCEPTIONS => [
Renderer::DEFAULT_STATUS => 500,
Renderer::MAP => [
'FooException' => 504,
'BarException' => [
Error::TITLE => 'Teapot',
Error::DETAIL => "I'm a teapot, not a server.",
Error::STATUS => 418,
],
],
],
];If providing an array template, then remember to include an Error::STATUS code so that the HTTP status of the response is set correctly.
If during the course of your application's logic you need to return a JSON API error object to the client, throw one of the following exceptions:
CloudCreativity\JsonApi\Error\ThrowableError- an exception that is an error object.CloudCreativity\JsonApi\Error\ErrorException- an exception that takes aNeormerx\JsonApi\Contracts\Document\ErrorInterfaceobject as its first argument, effectively allowing you to throw an error object.CloudCreativity\JsonApi\Error\MultiErrorException- an exception that takes aCloudCreativity\Jsonapi\Contracts\Error\ErrorCollectionInterfaceobject as its first object.
None of the above classes need to be registered in your config file's exception map because the renderer automatically handles them.