JSON:API Resources en Laravel 13

Qué es JSON:API y por qué usarlo

JSON:API es un estándar (especificación jsonapi.org) que define cómo estructurar respuestas de APIs REST en JSON. Incluye:

• Recursos con type e id
• Atributos y relaciones
• Sparse fieldsets (campos opcionales)
• Cabecera Content-Type: application/vnd.api+json

Laravel 13 incorpora soporte nativo para JSON:API mediante la clase JsonApiResource, que sustituye o complementa a las tradicionales API Resources (JsonResource) cuando quieres cumplir el estándar.

Usar JSON:API facilita la interoperabilidad con clientes que consumen APIs estándar y evita reinventar estructuras de respuesta propias.

Crear un JsonApiResource

Genera un recurso con Artisan:

php artisan make:resource PostResource --json-api

En el archivo generado definirás los atributos y las relaciones:

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\JsonApiResource;

class PostResource extends JsonApiResource
{
    public function toArray($request): array
    {
        return [
            'title' => $this->title,
            'body' => $this->body,
            'published_at' => $this->published_at?->toIso8601String(),
        ];
    }

    public function toRelationships($request): array
    {
        return [
            'author' => fn () => UserResource::make($this->whenLoaded('author')),
            'comments' => fn () => CommentResource::collection($this->whenLoaded('comments')),
        ];
    }
}

toArray devuelve los atributos del recurso. toRelationships define las relaciones disponibles para incluir en respuestas compuestas.

Devolver recursos en el controlador

Para un solo modelo:

return new PostResource($post);

Para una colección:

return PostResource::collection(Post::all());

También puedes usar el método toResourceCollection() sobre un conjunto de modelos:

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

El framework se encarga de enviar la cabecera Content-Type: application/vnd.api+json y de estructurar el JSON según JSON:API.

Sparse fieldsets y includes

Los clientes JSON:API suelen pedir campos concretos (fields[post]=title,body) e incluir relaciones (include=author,comments). JsonApiResource y el encabezado de la petición permiten que Laravel filtre automáticamente los atributos y relaciones devueltos. La implementación interna del paquete se encarga de respetar estos parámetros cuando el cliente los envía.