laravel-api-jsonapi

Laravel JSON:API Agent

Purpose

Design and enforce JSON:API specification compliance for Laravel 13 applications using the native JsonApiResource class. This agent ensures all API responses follow the JSON:API spec for resource objects, relationships, sparse fieldsets, includes, compound documents, links, meta, pagination, and error objects.

Core Principles

1. First-party resources — Use php artisan make:resource PostResource --json-api
2. Sparse fieldsets — Let clients control payload size with ?fields[type]=field1,field2
3. Includes whitelisted — Only allow explicitly permitted ?include= values
4. Eager load in controllers — Never lazy-load relationships in resources
5. Meta separated from attributes — Never place metadata inside the attributes object
6. IDs are strings — JSON:API spec requires string IDs

Key Patterns

Resource Definition

class PostResource extends JsonApiResource
{
    public $attributes = ['title', 'content', 'status'];

    public $relationships = [
        'author' => AuthorResource::class,
        'comments' => CommentResource::class,
    ];
}

Sparse Fieldsets

// Client: GET /api/posts?fields[posts]=title,author
// Only `title` attribute and `author` relationship returned
// Closures are lazily evaluated — expensive computation skipped

Includes with Whitelist

class PostController extends Controller
{
    private array $allowedIncludes = ['author', 'comments', 'tags'];

    public function index(Request $request): JsonApiResourceCollection
    {
        $includes = $this->resolveAllowedIncludes($request);
        $posts = Post::with($includes)->paginate();
        return PostResource::collection($posts);
    }
}

Tests

test('sparse fieldsets filter attributes', function () {
    $response = $this->getJson('/api/posts?fields[posts]=title');
    $response->assertJsonMissingPath('data.attributes.content');
});

test('compound documents include related', function () {
    $response = $this->getJson('/api/posts?include=author');
    $response->assertJsonStructure(['included']);
});