How to Use Laravel JSON:API to Create a JSON API Compliant Backend in Laravel

What we'll be doing

In this article we'll build a simple JSON API compliant set of APIs which will allow us to create tasks and attach assignees to them. Additionally, we'll also test a few endpoints to make sure they work properly.

In order to quickly prototype our APIs we'll be using an amazing Laravel library called Laravel JSON:API.

Why use JSON:API?

• Standardized, consistent APIs
• Feature rich - some of which are: sparse fieldsets (only fetch the fields you need), filtering, sorting, pagination, eager loading for relationships (includes, which solve the N+1 Problem)
• Easy to understand

Why use Laravel JSON:API?

• It saves a lot of development time
• Highly maintainable code
• Great, extensive documentation
• Strong conventions (in terms of naming), but highly customizable
• Makes use of native laravel features such as policies and form requests to make the shift easier for developers (we'll see later what this is about)

Prerequisites

• Composer installed on your machine
• A working database connection
• A running (preferably fresh) Laravel application

Main Packages used and their versions

• Laravel 8.0
• Laravel JSON:API 1.0
• Laravel JSON:API Testing 1.0

Installation

We'll start by installing the Laravel JSON:API core and testing packages:

composer require laravel-json-api/laravel

composer require --dev laravel-json-api/testing

Setup

Now that we have everything installed, let's publish (instruct Laravel to get all the "publishable" assets from the vendor package we choose and place them in our project directory in their respective folders) the configuration file and start customizing:

php artisan vendor:publish --provider="LaravelJsonApi\Laravel\ServiceProvider"

The published config file will look like this:

return [
  /*
  |--------------------------------------------------------------------------
  | Root Namespace
  |--------------------------------------------------------------------------
  | The root JSON:API namespace, within your application's namespace.
  | This is used when generating any class that does not sit *within*
  | a server's namespace. For example, new servers and filters.
  | By default this is set to `JsonApi` which means the root namespace
  | will be `\App\JsonApi`, if your application's namespace is `App`.
  */
  'namespace' => 'JsonApi',

  /*
  |--------------------------------------------------------------------------
  | Servers
  |--------------------------------------------------------------------------
  | A list of the JSON:API compliant APIs in your application, referred to
  | as "servers". They must be listed below, with the array key being the
  | unique name for each server, and the value being the fully-qualified
  | class name of the server class.
  */
  'servers' => [
    // 'v1' => \App\JsonApi\V1\Server::class,
  ],
];

Now we need to generate a server file and then uncomment the entry in the servers array:

php artisan jsonapi:server v1

With our application configured, we can start generating and writing the necessary code in order to achieve our goal.

Laravel files

In this section we will generate the necessary task model and migrations. Also, since we will test our endpoints at the end, we will create an additional factory for the tasks. However, we won't start filling out the factory until the testing phase.

In order to generate these files run the following command:

php artisan make:model Task -mf

With this command we instruct artisan to create a model and the corresponding migration and factory.

Json Api Files

Given that we have our migrations and models in place, we can start generating the Laravel JSON:API resources.

Tests

We've finally registered all the necessary resources! We just need to fill in the TaskFactory and we're ready to get on with testing:

We'll stop here, but if you want to test the rest of the actions take a look at this chapter in the documentation.