laravel-jsonapi

Laravel 13 JSON:API Resources

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:

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

Feature	Description
JsonApiResource	Base class extending JsonResource with spec compliance
Content-Type	Auto-sets application/vnd.api+json
Sparse fieldsets	?fields[posts]=title,created_at
Inclusion	?include=author,comments with included array
Resource identifiers	{"id":"1","type":"posts"} in relationships
Links / meta	toLinks() / toMeta() overrides

---

Critical Rules

1. Extend JsonApiResource - Never roll your own JSON:API serializer; the base class handles spec edge cases
2. Type is derived from the class name (PostResource → posts) - override toType() only when it must differ
3. Use $attributes / toAttributes() not toArray() - JSON:API splits attributes from identifiers; mixing them breaks compliance
4. Whitelist relationships - Declare $relationships (or toRelationships()) with 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

Topic	Reference	When to Consult
Base resource class	resources.md	Structuring JsonApiResource subclasses
Sparse fieldsets	sparse-fieldsets.md	Implementing fields[type]=a,b
Relationships	relationships.md	Inclusion + identifiers + links

Templates

Template	When to Use
PostResource.php.md	Resource with belongsTo + hasMany
UserResource.php.md	Simple resource with sparse fields

---

Quick Reference

Minimal resource

// php artisan make:resource PostResource --json-api
use Illuminate\Http\Resources\JsonApi\JsonApiResource;

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

    public $relationships = ['author', 'comments'];
}

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
• Override toType() only when the derived type must differ from the class name (e.g. AuthorResource wrapping User)
• Use toLinks() to expose self / related 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 / toRelationships() - 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