> JSON:API nativo in Laravel 13: API conformi allo standard senza pacchetti esterni

Perche JSON:API e perche adesso

La specifica JSON:API definisce un formato standard per le risposte delle API REST: struttura dei dati, inclusione di relazioni, paginazione, filtri, ordinamento e link. E uno standard maturo, utilizzato da aziende come Stripe, Shopify e Digital Ocean per le loro API pubbliche.

Fino a Laravel 12, implementare JSON:API in un progetto Laravel richiedeva pacchetti di terze parti come spatie/laravel-json-api o laravel-json-api/laravel. Pacchetti validi, ma con le loro convenzioni, le loro dipendenze e il loro ciclo di aggiornamento che non sempre si allinea a quello del framework.

Laravel 13 porta il supporto JSON:API direttamente nel core, con classi resource dedicate che gestiscono la serializzazione, le relazioni e la conformita allo standard in modo nativo.

Cosa gestisce il framework automaticamente

Ecco le funzionalita JSON:API che Laravel 13 supporta out of the box:

• Serializzazione automatica: i modelli Eloquent vengono trasformati nel formato JSON:API con type, id e attributes senza configurazione manuale. Basta estendere la classe JsonApiResource al posto della classica JsonResource.
• Relationship inclusion: il parametro ?include=tags,author carica e include le relazioni richieste nella risposta, con eager loading automatico per evitare problemi N+1.
• Sparse fieldsets: ?fields[articles]=title,slug restituisce solo i campi richiesti dal client, riducendo il payload e migliorando le performance.
• Links automatici: self, related e pagination links generati automaticamente seguendo le convenzioni della specifica.
• Header conformi: Content-Type: application/vnd.api+json impostato di default su tutte le risposte, con validazione automatica dell'header Accept nelle richieste.

Come creare una risorsa JSON:API in Laravel 13

Il processo e simile alla creazione di una API Resource tradizionale, con alcune differenze nella classe base e nei metodi disponibili:

• Si crea una classe che estende JsonApiResource
• Si definisce il metodo toAttributes() per specificare i campi esposti
• Si definisce il metodo toRelationships() per dichiarare le relazioni disponibili
• Si registra la risorsa nelle rotte come qualsiasi altra API Resource

Il framework si occupa di tutto il resto: formattazione, link, meta, gestione dei parametri di query e negoziazione dei content type.

Filtri, ordinamento e paginazione

Filtri conformi allo standard

Laravel 13 gestisce i filtri JSON:API tramite il parametro ?filter[campo]=valore. I filtri vengono mappati automaticamente sugli scope Eloquent del modello, mantenendo la logica di query nel model e la conformita allo standard nella risposta.

Ordinamento flessibile

Il parametro ?sort=title,-created_at ordina i risultati per titolo ascendente e data di creazione discendente. Il prefisso - indica l'ordine discendente, come definito dalla specifica. Il framework valida i campi ordinabili e restituisce un errore conforme se il client richiede un ordinamento non supportato.

Paginazione standard

La paginazione usa i parametri ?page[number]=2&page[size]=25 e genera automaticamente i link first, last, prev e next nel blocco links della risposta. Il client non deve calcolare nulla: segue i link forniti dal server.

Error handling conforme alla specifica

Quando qualcosa va storto, la risposta di errore segue il formato JSON:API:

• Errori di validazione restituiti con status 422 e dettaglio per ogni campo
• Errori di autenticazione con status 401 e messaggio standard
• Risorse non trovate con status 404 e formato conforme
• Ogni errore include status, title, detail e opzionalmente source

Questo significa che il client puo gestire gli errori in modo uniforme, senza dover interpretare formati diversi per situazioni diverse.

Quando usare JSON:API e quando no

JSON:API e la scelta giusta quando:

• L'API deve essere consumata da client che seguono lo standard, come Ember.js o client generati automaticamente da strumenti come openapi-generator
• L'API e pubblica e serve documentazione e convenzioni chiare per gli sviluppatori esterni
• Il progetto richiede gestione avanzata di relazioni, filtri e paginazione standardizzata
• Si lavora in team e serve un formato che elimini ambiguita sulla struttura delle risposte

JSON:API non e necessario quando:

• L'API e interna e consumata solo dal frontend dello stesso progetto
• Le risposte sono semplici e non richiedono relazioni complesse
• Il team ha gia convenzioni consolidate con le API Resource classiche di Laravel

Migrazione da pacchetti di terze parti

Per chi usa gia spatie/laravel-json-api o pacchetti simili, la migrazione al supporto nativo richiede di riscrivere le classi resource usando le nuove classi base di Laravel. La logica e simile, ma i metodi e le convenzioni sono leggermente diversi. Il consiglio e migrare gradualmente, endpoint per endpoint, verificando la conformita con i test esistenti.

Per progetti nuovi, partire direttamente con il supporto nativo elimina una dipendenza e garantisce che la compatibilita con il framework sia sempre allineata.