Cos'è GraphQL e quando usarlo

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:

1. Il server definisce uno schema che descrive tutti i dati disponibili e le loro relazioni.
2. Il client invia una query specificando esattamente quali campi vuole.
3. 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.