laravel-jsonapi

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

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	self, related links auto-generated

---

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

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

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