Laravel 13 JSON:API Resources

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

1. fuse-ai-pilot:explore-codebase - Inventory existing JsonResource classes to migrate
2. fuse-ai-pilot:research-expert - Check JSON:API v1.1 spec for required headers and structure
3. mcp__context7__query-docs - Pull laravel.com/docs/13.x/eloquent-resources examples

After implementation, run fuse-ai-pilot:sniper for validation.

Overview

Critical Rules

1. Extend JsonApiResource - Never roll your own JSON:API serializer; the base class handles spec edge cases
2. Declare $type - Each resource MUST set a string $type (e.g., posts, users)
3. Use toAttributes() not toArray() - JSON:API splits attributes from identifiers; mixing them breaks compliance
4. Whitelist relationships - Implement relationships() returning only the relations clients may include
5. Respect Content-Type - Clients sending JSON:API requests MUST use Accept: application/vnd.api+json

Architecture

app/Http/Resources/
├── PostResource.php           # extends JsonApiResource, $type = 'posts'
├── UserResource.php           # extends JsonApiResource, $type = 'users'
└── CommentResource.php        # extends JsonApiResource, $type = 'comments'

app/Http/Controllers/
└── Api/PostController.php     # returns PostResource::collection($posts)

→ See PostResource.php.md for full example

Reference Guide

Templates

Quick Reference

Minimal resource

use Illuminate\Http\Resources\Json\JsonApiResource;

class PostResource extends JsonApiResource
{
    public string $type = 'posts';

    public function toAttributes($request): array
    {
        return ['title' => $this->title, 'body' => $this->body];
    }
}

Controller

return PostResource::collection(Post::with('author')->get());

→ See PostResource.php.md for complete example

Best Practices

DO

• Eager-load relationships used in include to avoid N+1 (?include=author → with('author'))
• Document supported include and fields parameters in your OpenAPI spec
• Set explicit $type matching the URL segment (e.g., /api/posts → 'posts')
• Use toLinks() to expose self, related, pagination links

DON'T

• Don't return a JSON:API response without the JsonApiResource base class - manual JSON breaks subtle spec rules (e.g., null vs empty data)
• Don't include relationships not whitelisted in relationships() - silent ignoring keeps APIs predictable
• Don't mix toArray() and toAttributes() - the JSON:API base class expects the latter
• Don't forget to set the response Content-Type when bypassing resources (e.g., custom errors) - clients may reject the response