While this tutorial has content that we believe is of great benefit to our community, we have not yet tested or edited it to ensure you have an error-free learning experience. It's on our list, and we're working on it! You can help us out by using the "report an issue" button at the bottom of the tutorial.

Introduction

When creating APIs, we often need to work with database results to filter, interpret or format values that will be returned in the API response. API resource classes allow you to convert your models and model collections into JSON, working as a data transformation layer between the database and the controllers.

API resources provide a uniform interface that can be used anywhere in the application. Eloquent relationships are also taken care of.

Laravel provides two artisan commands for generating resources and collections - we’ll understand the difference between these two later on. But for both resources and collections, we have our response wrapped in a data attribute: a JSON response standard.

We’ll look at how to work with API resources in the next section by playing around with a demo project.

Prerequisites:

To follow along with this guide, you need to meet the following prerequisites:

Obtaining the Demo Code

Clone this repo and follow the instructions in the README.md to get things up and running.

With the project setup, we can now start getting our hands dirty. Also, since this is a very small project, we won’t be creating any controllers and will instead test out responses inside route closures.

Let’s start by generating a SongResource class:

  • php artisan make:resource SongResource

If we peek inside the newly created resource file i.e. SongResource (Resource files usually go inside the App\Http\Resources folder), the contents looks like this:

[...]
class SongResource extends JsonResource
{
    /**
    * Transform the resource into an array.
    * 
    *  @param  \Illuminate\Http\Request  $request
    *  @return array
    **/
    public function toArray($request)
    {
        return parent::toArray($request);
    }
}

By default, we have parent::toArray($request) inside the toArray() method. If we leave things at this, all visible model attributes will be part of our response. To tailor the response, we specify the attributes we want to be converted to JSON inside this toArray() method.

Let’s update the toArray() method to match the snippet below:

public function toArray($request)
{
    return [
        'id' => $this->id,
        'title' => $this->title,
        'rating' => $this->rating,
    ];
}

As you can see, we can access the model properties directly from the $this variable because a resource class automatically allows method access down to the underlying model.

Let’s now update the routes/api.php with the snippet below:

# routes/api.php

[...]
use App\Http\Resources\SongResource;
use App\Song;
[...]

Route::get('/songs/{song}', function(Song $song) {
    return new SongResource($song);
});

Route::get('/songs', function() {
    return new SongResource(Song::all());
});

If we visit the URL /api/songs/1, we’ll see a JSON response containing the key-value pairs we specified in the SongResource class for the song with an id of 1:

{
  data: {
    id: 1,
    title: "Mouse.",
    rating: 3
  }
}

However, if we try visiting the URL /api/songs, an Exception is thrown Property [id] does not exist on this collection instance.

This is because instantiating the SongResource class requires a resource instance be passed to the constructor and not a collection. That’s why the exception is thrown.

If we wanted a collection returned instead of a single resource, there is a static collection() method that can be called on a Resource class passing in a collection as the argument. Let’s update our songs route closure to this:

Route::get('/songs', function() {
    return SongResource::collection(Song::all());
});

Visiting the /api/songs URL again will give us a JSON response containing all the songs.

{
  data: [{
      id: 1,
      title: "Mouse.",
      rating: 3
    },
    {
      id: 2,
      title: "I'll.",
      rating: 0
    }
  ]
}

Resources work just fine when returning a single resource or even a collection but have limitations if we want to include metadata in the response. That’s where Collections come to our rescue.

To generate a collection class, we run:

php artisan make:resource SongsCollection

The main difference between a JSON resource and a JSON collection is that a resource extends the JsonResource class and expects a single resource to be passed when being instantiated while a collection extends the ResourceCollection class and expects a collection as the argument when being instantiated.

Back to the metadata bit. Assuming we wanted some metadata such as the total song count to be part of the response, here’s how to go about it when working with the ResourceCollection class:

class SongsCollection extends ResourceCollection
{
    public function toArray($request)
    {
        return [
            'data' => $this->collection,
            'meta' => ['song_count' => $this->collection->count()],
        ];
    }
}

If we update our /api/songs route closure to this:

[...]
use App\Http\Resources\SongsCollection;
[...]
Route::get('/songs', function() {
    return new \SongsCollection(Song::all());
});

And visit the URL /api/songs, we now see all the songs inside the data attribute as well as the total count inside the meta bit:

{
  data: [{
      id: 1,
      title: "Mouse.",
      artist: "Carlos Streich",
      rating: 3,
      created_at: "2018-09-13 15:43:42",
      updated_at: "2018-09-13 15:43:42"
    },
    {
      id: 2,
      title: "I'll.",
      artist: "Kelton Nikolaus",
      rating: 0,
      created_at: "2018-09-13 15:43:42",
      updated_at: "2018-09-13 15:43:42"
    },
    {
      id: 3,
      title: "Gryphon.",
      artist: "Tristin Veum",
      rating: 3,
      created_at: "2018-09-13 15:43:42",
      updated_at: "2018-09-13 15:43:42"
    }
  ],
  meta: {
    song_count: 3
  }
}

But we have a problem, each song inside the data attribute is not formatted to the specification we defined earlier inside the SongResource and instead has all attributes.

To fix this, inside the toArray() method, set the value of data to SongResource::collection($this->collection) instead of having $this->collection.

Our toArray() method should now look like this:

public function toArray($request)
{
    return [
        'data' => SongResource::collection($this->collection),
       'meta' => ['song_count' => $this->collection->count()]
    ];
}

You can verify we get the correct data in the response by visiting the /api/songs URL again.

What if one wants to add metadata to a single resource and not a collection? Luckily, the JsonResource class comes with an additional() method which lets you specify any additional data you’d like to be part of the response when working with a resource:

Route::get('/songs/{song}', function(Song $song) {
    return (new SongResource(Song::find(1)))->additional([
        'meta' => [
            'anything' => 'Some Value'
        ]
    ]);
})

In this case, the response would look somewhat like this:

{
  data: {
    id: 1,
    title: "Mouse.",
    rating: 3
  },
  meta: {
    anything: "Some Value"
  }
}

Creating Model Relationships

In this project, we only have two models, Album and Song. The current relationship is a one-to-many relationship, meaning an album has many songs and a song belongs to an album.

We’ll now update the toArray() method inside the SongResource class so that it references the album:

class SongResource extends JsonResource
{
    public function toArray($request)
    {
        return [
            // other attributes
            'album' => $this->album
        ];
    }
}

If we want to be more specific in terms of what album attributes should be present in the response, we can create an AlbumResource similar to what we did with songs.

To create the AlbumResource, run:

  • php artisan make:resource AlbumResource

Once the resource class has been created, we then specify the attributes we want to be included in the response.

class AlbumResource extends JsonResource
{
    public function toArray($request)
    {
        return [
            'title' => $this->title
        ];
    }
}

And now inside the SongResource class, instead of doing 'album' => $this->album, we can make use of the AlbumResource class we just created.

class SongResource extends JsonResource
{
    public function toArray($request)
    {
        return [
            // other attributes
            'album' => new AlbumResource($this->album)
        ];
    }
}

If we visit the /api/songs URL again, you’ll notice an album will be part of the response. The only problem with this approach is that it brings up the N + 1 query problem.

For demonstration purposes, add the snippet below inside the api/routes file:

# routes/api.php

[...]
\DB::listen(function($query) {
    var_dump($query->sql);
});

Visit the /api/songs URL again. Notice that for each song, we make an extra query to retrieve the album’s details? This can be avoided by eager loading relationships. In our case, update the code inside the /api/songs route closure to:

return new SongsCollection(Song::with('album')->get());

Reload the page again and you’ll notice the number of queries has reduced. Comment out the \DB::listen snippet since we don’t need that anymore.

Using Conditionals When Working with Resources

Every now and then, we might have a conditional determining the type of response that should be returned.

One approach we could take is introducing if statements inside our toArray() method. The good news is we don’t have to do that as there is a ConditionallyLoadsAttributes trait required inside the JsonResource class that has a handful of methods for handling conditionals. Just to mention a few, we have the when(), whenLoaded() and mergeWhen() methods.

We’ll only brush through a few of these methods, but the documentation is quite comprehensive.

The whenLoaded method

This method prevents data that has not been eagerly loaded from being loaded when retrieving related models thereby preventing the (N+1) query problem.

Still working with the Album resource as a point of reference (an album has many songs):

public function toArray($request)
{
    return [
        // other attributes
        'songs' => SongResource::collection($this->whenLoaded($this->songs))
    ];
}

In the case where we are not eagerly loading songs when retrieving an album, we’ll end up with an empty songs collection.

The mergeWhen Method

Instead of having an if statement that dictates whether some attribute and its value should be part of the response, we can use the mergeWhen() method which takes in the condition to evaluate as the first argument and an array containing key-value pair that is meant to be part of the response if the condition evaluates to true:

public function toArray($request)
{
    return [
        // other attributes
        'songs' => SongResource::collection($this->whenLoaded($this->songs)),
        this->mergeWhen($this->songs->count > 10, ['new_attribute' => 'attribute value'])
    ];
}

This looks cleaner and more elegant instead of having if statements wrapping the entire return block.

Unit Testing API Resources

Now that we’ve learned how to transform our responses, how do we actually verify that the response we get back is what we specified in our resource classes?

We’ll now write tests verifying the response contains the correct data as well making sure eloquent relationships are still maintained.

Let’s create the test:

  • php artisan make:test SongResourceTest --unit

Notice the --unit flag when generating the test: this will tell Laravel that this should be a unit test.

Let’s start by writing the test to make sure our response from the SongResource class contains the correct data:

[...]
use App\Http\Resources\SongResource;
use App\Http\Resources\AlbumResource;
[...]
class SongResourceTest extends TestCase
{
    use RefreshDatabase;
    public function testCorrectDataIsReturnedInResponse()
    {
        $resource = (new SongResource($song = factory('App\Song')->create()))->jsonSerialize();
    }
}

Here, we first create a song resource then call jsonSerialize() on the SongResource to transform the resource into JSON format, as that’s what should be sent to our front-end.

And since we already know the song attributes that should be part of the response, we can now make our assertion:

$this->assertArraySubset([
    'title' => $song->title,
    'rating' => $song->rating
], $resource);

In this example, we’ve matched two attributes: title and rating. You can list as many attributes as you would like.

If you want to make sure your model relationships are preserved even after converting models to resources, you can use:

public function testSongHasAlbumRelationship()
{
    $resource = (new SongResource($song = factory('App\Song')->create(["album_id" => factory('App\Album')->create(['id' => 1])])))->jsonSerialize();
}

Here, we create a song with an album_id of 1 then pass the song on to the SongResource class before finally transforming the resource into JSON format.

To verify that the song-album relationship is still maintained, we make an assertion on the album attribute of the $resource we just created. Like so:

$this->assertInstanceOf(AlbumResource::class, $resource["album"]);

Note, however, if we did $this->assertInstanceOf(Album::class, $resource["album"]) our test would fail since we are transforming the album instance into a resource inside the SongResource class.

As a recap, we first create a model instance, pass the instance to the resource class, convert the resource into JSON format before finally making the assertions.

Conclusion

We’ve looked at what Laravel API resources are, how to create them as well as how to test out various JSON responses. Feel free to explore the JsonResource class and see all the methods that are available.

If you would like to learn more about Laravel API resources, check the official documentation.

0 Comments

Creative Commons License