Cos'è GraphQL e quando usarlo
Cos'è GraphQL spiegato semplice: come funziona, differenze con le REST API, vantaggi come l'over-fetching evitato, svantaggi e quando conviene sceglierlo davvero.
GraphQL è spesso presentato come "l'alternativa moderna a REST", ma la verità è più sfumata: non è meglio o peggio in assoluto, è diverso, e brilla in scenari specifici. In questo articolo ti spiego cos'è GraphQL, come funziona e soprattutto quando conviene usarlo rispetto a una REST API.
Cos'è GraphQL in parole semplici
GraphQL è un linguaggio di interrogazione per API che permette al client di chiedere esattamente i dati che gli servono, né più né meno, con una sola richiesta. È stato creato per risolvere alcuni limiti pratici delle REST API tradizionali.
La differenza fondamentale: con REST il server decide la forma dei dati che restituisce; con GraphQL è il client a specificare cosa vuole ricevere.
Il problema che GraphQL risolve
Con le REST API capitano due problemi ricorrenti:
- Over-fetching: ricevi più dati di quelli che ti servono. Chiedi un utente e ottieni venti campi quando te ne servono due.
- Under-fetching: ricevi meno dati di quelli che ti servono, costringendoti a fare più richieste a endpoint diversi.
GraphQL elimina entrambi: chiedi esattamente i campi che vuoi, anche da risorse collegate, in una sola richiesta.
Come funziona GraphQL
Il funzionamento di base:
- Il server definisce uno schema che descrive tutti i dati disponibili e le loro relazioni.
- Il client invia una query specificando esattamente quali campi vuole.
- Il server risponde con una struttura dati che corrisponde esattamente alla query.
A differenza di REST, che ha tanti endpoint, GraphQL ha tipicamente un solo endpoint a cui invii query diverse a seconda di ciò che ti serve.
GraphQL vs REST
| Aspetto | REST | GraphQL |
|---|---|---|
| Endpoint | Molti, uno per risorsa | Uno solo |
| Dati restituiti | Decisi dal server | Decisi dal client |
| Over/under-fetching | Frequente | Evitato |
| Curva di apprendimento | Più dolce | Più ripida |
| Caching | Semplice (basato su HTTP) | Più complesso |
Da notare: la flessibilità di GraphQL ha un prezzo in termini di complessità. Il caching, che con REST è quasi gratis grazie a HTTP, con GraphQL richiede più lavoro.
I vantaggi di GraphQL
- Efficienza dei dati: chiedi solo ciò che ti serve, utile soprattutto su mobile e connessioni lente.
- Una sola richiesta per dati che con REST richiederebbero più chiamate.
- Schema fortemente tipizzato: il contratto dei dati è chiaro e auto-documentante.
- Evoluzione senza rotture: puoi aggiungere campi senza creare nuove versioni dell'API.
Gli svantaggi
- Maggiore complessità lato server, da configurare e ottimizzare.
- Caching più difficile rispetto a REST.
- Curva di apprendimento più ripida per chi inizia.
- Possibili query troppo costose se non si pongono limiti.
Quando usare GraphQL (e quando no)
GraphQL conviene quando:
- Hai client diversi (web, mobile, ecc.) con esigenze di dati differenti.
- I dati sono molto interconnessi e fai query complesse su più risorse.
- Vuoi ridurre il numero di richieste e i dati trasferiti.
REST è preferibile quando:
- L'API è semplice e i dati hanno una struttura prevedibile.
- Il caching HTTP è importante.
- Vuoi semplicità e una curva di apprendimento più dolce.
Il mio consiglio: se inizi, parti da REST, che è più semplice e copre la maggioranza dei casi. Passa a GraphQL quando hai un problema reale che giustifica la sua complessità, non perché "è moderno".
In sintesi
GraphQL è un linguaggio di interrogazione per API che permette al client di chiedere esattamente i dati che gli servono, in una sola richiesta, eliminando over-fetching e under-fetching. È potente e flessibile, ma più complesso di REST, soprattutto sul caching. Conviene con client diversi e dati molto interconnessi; per casi semplici, REST resta la scelta più pragmatica.
Per il confronto completo, vedi cos'è una REST API e cos'è un'API.