Guide

GraphQL è un linguaggio di query per le API e, al tempo stesso, un runtime che risponde a quelle query con i tuoi dati. Creato in Facebook nel 2012 e rilasciato come open source nel 2015, offre al client — un front-end web, un'app mobile o un altro servizio — un modo unico e preciso di chiedere a un server esattamente i dati di cui ha bisogno, né più né meno. Invece che sia il server a decidere la forma di ogni risposta, è il client a descrivere ciò che vuole, e il server restituisce i dati nella stessa forma.

Questa singola idea è ciò che distingue GraphQL dallo stile REST che lo ha preceduto. Con REST di solito chiami diversi endpoint, ciascuno dei quali restituisce una struttura fissa definita in anticipo dal server. Con GraphQL invii una sola richiesta a un unico endpoint e specifichi i campi che vuoi; la risposta rispecchia la tua richiesta. L'obiettivo non è rendere REST obsoleto, ma risolvere problemi specifici che gli endpoint fissi creano man mano che un'applicazione e i suoi dati crescono.

Come funziona GraphQL: lo schema

Al cuore di GraphQL c'è lo schema, un contratto fortemente tipizzato che descrive ogni tipo di dato disponibile e il modo in cui questi tipi sono in relazione. Poiché lo schema è esplicito e tipizzato, entrambe le parti sanno in anticipo ciò che è possibile: gli strumenti possono validare una query prima ancora che venga eseguita, gli editor possono completare automaticamente i campi e la documentazione può essere generata automaticamente dallo schema stesso. Questa natura autodescrittiva è uno dei vantaggi più concreti di GraphQL.

Una query GraphQL si legge quasi come il JSON che restituisce. Nomini i campi che vuoi, annidi all'interno i campi correlati e il server percorre lo schema per risolvere ciascuno di essi. Lo stesso endpoint accetta anche le mutation, che modificano i dati, e le subscription, che permettono al server di inviare aggiornamenti al client tramite una connessione persistente. Query, mutation e subscription sono i tre tipi di operazione definiti dalla specifica.

Over-fetching e under-fetching

Due problemi degli endpoint REST fissi spiegano gran parte dell'attrattiva di GraphQL: l'over-fetching e l'under-fetching. L'over-fetching si verifica quando un endpoint restituisce molti più dati di quanti ne serva una schermata, sprecando banda. L'under-fetching è il contrario: un singolo endpoint non restituisce abbastanza, così il client deve fare diversi viaggi di andata e ritorno per comporre un'unica vista. Poiché un client GraphQL chiede con precisione i campi necessari in una sola richiesta, evita entrambi in un colpo solo.

• Linguaggio di query per API: il client chiede esattamente i campi che gli servono
• Schema fortemente tipizzato = autodocumentato, validato, con autocompletamento
• Tre operazioni: query (lettura), mutation (scrittura), subscription (push)
• Risolve over- e under-fetching di REST in un'unica richiesta
• Compromessi: caching HTTP più difficile, tutele sul costo; REST più semplice per piccole API

GraphQL e i framework front-end

Questa precisione è particolarmente preziosa per i framework front-end come React, Vue, Svelte e Angular, dove un componente ha spesso bisogno di una porzione precisa di dati. Un componente può chiedere esattamente i campi che renderizza e, man mano che l'interfaccia evolve, la query evolve con essa, senza attendere che un team di back-end crei un nuovo endpoint. Librerie client mature aggiungono in cima caching, raggruppamento delle richieste e gestione dello stato, ed è per questo che GraphQL è diventato popolare nei front-end orientati ai componenti.

I compromessi, in tutta onestà

GraphQL non è automaticamente la scelta giusta, ed essere onesti sui suoi compromessi conta. Il suo unico endpoint dinamico rende più difficile il semplice caching HTTP di cui gode REST, perciò il caching di solito si sposta nel client o in uno strato specializzato. Query scritte con noncuranza possono chiedere dati profondamente annidati e mettere sotto sforzo il server, motivo per cui le API in produzione aggiungono limiti di profondità, analisi del costo e altre tutele. Per una piccola API con esigenze stabili e prevedibili, REST è spesso più semplice e perfettamente sufficiente.

Ciò che GraphQL non è

Vale anche la pena chiarire ciò che GraphQL non è. Non è un database né un motore di archiviazione: si colloca davanti alle tue fonti di dati esistenti — siano esse database, API REST o altri servizi — e i resolver vi attingono. Non è nemmeno legato a un singolo linguaggio o framework; server e client esistono in tutto l'ecosistema, e la specifica è mantenuta dalla GraphQL Foundation, neutrale rispetto ai fornitori, e non da una singola azienda.

GraphQL vs REST: come scegliere

Scegliere tra GraphQL e REST dipende dalla forma della tua applicazione, non dalla moda. GraphQL eccelle quando molti client diversi hanno bisogno di porzioni diverse di un grafo di dati complesso e interconnesso, quando i team di front-end e back-end vogliono procedere in modo indipendente, o quando ridurre i viaggi di andata e ritorno su connessioni lente è una priorità. REST resta un'ottima scelta predefinita per servizi più semplici, API pubbliche che traggono vantaggio dal caching HTTP e team che ne apprezzano l'ubiquità e la semplicità.

Detto in modo semplice, GraphQL è un modo per lasciare che il client chieda esattamente i dati che vuole, descritti da uno schema tipizzato, serviti da un unico endpoint. Non sostituisce né i database, né REST, né i tuoi servizi esistenti; organizza il modo in cui i client dialogano con essi. Sapere quali problemi risolve — e i costi di caching e complessità che introduce — è ciò che ti permette di ricorrervi quando si adatta davvero e di lasciarlo da parte quando REST è lo strumento migliore.