GraphQL over HTTP rende gli errori visibili anche fuori dal JSON
La prima specifica GraphQL over HTTP identifica le risposte con un formato dedicato e permette codici d’errore più informativi. Per i risultati parziali raccomanda il 294, ancora non registrato come status HTTP ufficiale.
Che succede
Un servizio GraphQL può restituire errori dentro una risposta HTTP marcata 200 OK. L’applicazione li vede leggendo il JSON; un monitor che guarda soltanto il codice può registrare che va tutto bene. La prima versione della specifica GraphQL over HTTP, pubblicata il 12 novembre, dà a questa differenza una sistemazione condivisa.
Il problema nasce anche dal formato: con il generico application/json, un client non sa dal solo tipo di contenuto se ha ricevuto una risposta GraphQL oppure il messaggio d’errore di un proxy intermedio. Il tipo application/graphql-response+json identifica invece il formato GraphQL. Il client può leggerlo anche quando il codice HTTP segnala un errore, senza dover usare il 200 come lasciapassare.
Questo permette di distinguere i casi anche nei log: una query non valida può ricevere 422, mentre un problema del server prima dell’esecuzione può usare un codice 5xx. Quando arrivano dati insieme a errori di esecuzione, la risposta resta nella famiglia dei successi 2xx: una parte del lavoro può essere riuscita. La specifica raccomanda per questo il codice personalizzato 294 Partial Success, che non è ancora uno status HTTP ufficiale registrato presso IANA.
Il JSON continua a raccontare che cosa è successo ai singoli campi: il codice HTTP non lo sostituisce. E la pubblicazione del documento non cambia da sola i server già in uso. Client, server e intermediari devono supportare il formato e gestire i codici scelti; le note della specifica richiamano proprio il caso del 294, che alcune infrastrutture possono trattare diversamente dal 200.
Il documento codifica anche URL, richieste GET e POST, header e codifica JSON. Si aggiunge alla specifica principale di GraphQL, che resta indipendente dal trasporto: il linguaggio delle query non cambia. È il viaggio su HTTP a guadagnare regole comuni, dopo anni in cui gran parte di quel lavoro era affidata alle singole implementazioni.
Perché conta
Un log pieno di 200 può nascondere le query andate male a chi sorveglia il servizio. Identificare il formato della risposta consente di far parlare anche il codice HTTP, senza togliere al client il dettaglio degli errori nel JSON: due strumenti che osservano la stessa richiesta possono finalmente raccontarsi una storia più simile.
Leggi le fonti
GraphQL TSC — annuncio della prima specifica GraphQL over HTTPGraphQL over HTTP — specifica, codici e risultati parzialiVuoi sapere di più su pillole come questa?