json-api

Introducing the `JSON:API` Resource Package for Laravel

The JSON:API Resource package is a minimalistic yet powerful tool designed to integrate smoothly with Laravel, helping developers align their applications with the JSON:API specification. This package provides features such as sparse fieldsets, compound documents, and other essential functionalities right out of the box, ensuring your API adheres to the standard without unnecessary complexity.

Version Compatibility

This tool is dependable across various versions of PHP and Laravel, specifically:

PHP Versions: 8.1, 8.2, 8.3
Laravel Versions: 9.0, 10.0, 11.0

Installation Process

Getting started is straightforward with Composer, a tool for managing PHP dependencies. You can import the package from Packagist by executing:

composer require timacdonald/json-api

Getting Started

The package offers a JsonApiResource class that builds on Laravel's Eloquent API resource capabilities. It allows developers to keep leveraging Laravel's native API resources while introducing new internal APIs to handle specific JSON:API functionalities. Here’s a glimpse into setup:

Creating Your First `JSON:API` Resource

To illustrate the setup, consider creating a UserResource that extends JsonApiResource. This resource will expose user details like name, website, and twitter_handle:

<?php

namespace App\Http\Resources;

use TiMacDonald\JsonApi\JsonApiResource;

class UserResource extends JsonApiResource
{
    public $attributes = [
        'name',
        'website',
        'twitter_handle',
    ];
}

When a user resource is fetched through an API endpoint, it responds in JSON:API format:

{
  "data": {
    "type": "users",
    "id": "74812",
    "attributes": {
      "name": "Tim",
      "website": "https://timacdonald.me",
      "twitter_handle": "@timacdonald87"
    }
  }
}

Adding Relationships

Beyond basic attributes, the JSON:API Resource package simplifies linking related data. You can define relationships like "team" (HasOne) and "posts" (HasMany) by appending them to the $relationships array in your resource class:

<?php

namespace App\Http\Resources;

use TiMacDonald\JsonApi\JsonApiResource;

class UserResource extends JsonApiResource
{
    public $relationships = [
        'team' => TeamResource::class,
        'posts' => PostResource::class,
    ];
}

With the include query parameter, clients can request these relationships, dictating which nested data should be included in the response.

Eager Loading Considerations

The package doesn’t automatically eager load relationships, potentially leading to multiple database queries. Using packages like Spatie's Query Builder alongside JSON:API for Laravel helps optimize these queries effectively.

Diving Deeper

Advanced scenarios are adequately covered, with specialized methods to handle complex attribute logic (toAttributes()) and relationship inclusion strategies (toRelationships()). These options provide developers with the flexibility needed to conditionally render fields and relationships based on request data.

Sparse Fieldsets and Minimal Attributes

The package supports sparse fieldsets, allowing API consumers to specify which attributes they prefer, reducing payload size, and improving performance. You can also enforce minimal attributes, demanding explicit field requests for any data retrieval.

Customizing Resource Identification

For those requiring extensive customization, the package allows alterations in identifying resources (setting custom "id" and "type" rules) via your Laravel service providers.

In Summary

The JSON:API Resource package for Laravel is a robust solution for developers aiming to comply with the JSON:API specification without complicating their Laravel applications. Whether you aim to expose entities merely or require precise control over API responses, this package provides user-friendly interfaces and rich customization options to meet those needs efficiently.

Introducing the JSON:API Resource Package for Laravel