Introduction

"[...] A resource class represents a single model that needs to be transformed into a JSON structure [...]" (source Laravel docs.)

The ApiResource is an extended / adapted version of Laravel's JsonResource. It ensures that each Api Resource that you create has a "type" and a "self" link. Additionally, all of your Api Resources are registered in a Registrar.

How to create an Api Resource

Extend the ApiResource and implement the formatPayload() and type() methods.

use Aedart\Http\Api\Resources\ApiResource;
use Illuminate\Http\Request;
use App\Models\Address;

/**
 * @mixin Address
 */
class AddressResource extends ApiResource
{
    public function formatPayload(Request $request): array
    {
        return [
            'id' => $this->id,
            'street' => $this->street,
            'postal_code' => $this->postal_code,
            'city' => $this->city
        ];
    }

    public function type(): string
    {
        // Resource's type name (singular form)
        return 'address';
    }
}

Register Api Resource

Once you have created your Api Resource, you must register it in the Registrar. The easiest way of doing so, is by defining a new key-value pair inside your config/api-resources.php configuration file.

use App\Models\Address;
use App\Http\Resources\AddressResource;

return [

    /*
     |--------------------------------------------------------------------------
     | Api Resources
     |--------------------------------------------------------------------------
    */

    'registry' => [

        Address::class => AddressResource::class,

    ],
];

Usage

After your Api Resource has been registered, you can use it as you normally would with Laravel's JsonResource.

use Illuminate\Support\Facades\Route;
use App\Http\Resources\AddressResource;
use App\Models\Address;

Route::get('/addresses/{id}', function ($id) {
    return new AddressResource(Address::findOrFail($id));
});

The resulting JSON output will be something similar to this:

{
    "data": {
        "id": 5,
        "street": "24924 Macey Hill Suite 432",
        "postal_code": "17092",
        "city": "South Eric"
    },
    "meta": {
        "type": "address",
        "self": "http://localhost/addresses/5"
    }
}