Programmazione · web · API

REST vs GraphQL

Stai costruendo una API e il primo grande bivio è lo stile: REST o GraphQL. Risolvono lo stesso problema — far leggere e scrivere dati ai client via HTTP — ma mettono il controllo in mani diverse. Questa guida li confronta onestamente su recupero dei dati, cache, complessità e tooling, per scegliere con cognizione di causa.

La differenza fondamentale

• REST — molti endpoint (URL), ognuno dei quali restituisce una forma fissa di dati. Chiami /users/42 e ottieni ciò che quell’endpoint è fatto per restituire. È il server a decidere la forma.
• GraphQL — un solo endpoint a cui il client invia una query che nomina esattamente i campi voluti, e riceve solo quelli. È il client a decidere la forma.

Entrambi passano per HTTP e parlano in genere JSON. La differenza: chi controlla ciò che torna indietro.

La stessa richiesta, in due modi

Recuperare il nome di un utente e i titoli dei suoi post. In REST sono spesso due chiamate; in GraphQL una query precisa:

-- REST (spesso due andate e ritorni)
GET /users/42
GET /users/42/posts

-- GraphQL (una query, campi esatti)
POST /graphql
{ user(id: 42) { name posts { title } } }

Over-fetching e under-fetching

È l’argomento principale di GraphQL. Con le risposte fisse di REST, incontri spesso:

• L’over-fetching — l’endpoint restituisce ben più del necessario (decine di campi per mostrare un nome).
• L’under-fetching — un endpoint non basta, fai più chiamate per costruire uno schermo.

GraphQL evita entrambi: il client chiede esattamente i campi voluti, in una sola query. Per app con molti schermi (soprattutto mobili), questa precisione è la ragione principale di adozione.

Dove REST vince ancora

• Cache — URL distinti + GET fanno funzionare REST naturalmente con le cache HTTP e le CDN. GraphQL (POST verso un endpoint) richiede una cache client o query persistite.
• Semplicità — per dati orientati alle risorse, REST ha meno da imparare e da gestire; niente schema, resolver né limiti di costo delle query.
• Tooling e ubiquità — REST è ovunque, con un tooling maturo e gratuito e una curva di apprendimento dolce.

Dove GraphQL vince

• Dati flessibili e precisi — i client recuperano esattamente ciò di cui hanno bisogno, non di più.
• Meno andate e ritorni — dati collegati in una sola query invece di più chiamate.
• Uno schema tipizzato — un contratto auto-documentato e un tooling potente (introspezione, codegen).

Il costo: più complessità lato server (schema, resolver, protezione dalle query costose) e una cache da progettare anziché ottenuta gratis.

Come scegliere

• Prendi REST per API più semplici, orientate alle risorse, dove la cache HTTP gratuita, l’ubiquità e una curva dolce contano.
• Prendi GraphQL quando i client hanno esigenze di dati varie ed evolutive e vuoi evitare l’over/under-fetching — e puoi assorbire la complessità server in più.
• Entrambi va bene — molti sistemi espongono REST per l’accesso semplice/pubblico e GraphQL per le app client ricche.

Domande frequenti

Qual è la differenza tra REST e GraphQL?

REST e GraphQL sono due stili per costruire una API web. Una API REST espone molti URL (endpoint), ognuno dei quali restituisce una forma di dati fissa — chiami /users/42 e ottieni ciò che quell’endpoint restituisce. GraphQL espone un solo endpoint a cui il client invia una query che descrive esattamente i campi voluti, e riceve solo quelli. In breve: con REST il server decide la forma della risposta per endpoint; con GraphQL la decide il client per query. Entrambi passano per HTTP e scambiano in genere JSON.

GraphQL è migliore di REST?

Nessuno è universalmente migliore — fanno compromessi diversi. GraphQL brilla quando i client hanno bisogno di dati flessibili e precisi (es. schermi mobili vari) perché evita l’over-fetching e l’under-fetching e raggruppa più chiamate in una sola query. REST brilla per API semplici orientate alle risorse e beneficia di una cache HTTP gratuita e matura e di un tooling solido. GraphQL aggiunge complessità lato server (schema, resolver, controllo del costo delle query); REST può richiedere più andate e ritorni. Scegli in base alle esigenze di dati dei tuoi client, non alla moda.

Che cos’è l’over-fetching e l’under-fetching?

L’over-fetching è quando un endpoint restituisce più dati del necessario — chiedi un utente e ricevi decine di campi per mostrare solo un nome, sprecando banda. L’under-fetching è quando un endpoint non ne restituisce abbastanza, costringendoti a più chiamate per assemblare ciò che uno schermo richiede. REST ne è soggetto perché ogni endpoint ha una risposta fissa. GraphQL li evita lasciando che il client chieda esattamente i campi voluti in una sola query — è il suo principale punto di forza.

REST o GraphQL: quale si mette meglio in cache?

REST è generalmente più semplice da mettere in cache. Poiché REST usa URL distinti e metodi HTTP (soprattutto GET per le letture), funziona naturalmente con la cache HTTP, le CDN e la cache del browser indicizzate sull’URL. GraphQL invia in genere le query in POST verso un solo endpoint, quindi la cache HTTP standard non si applica da subito, e ti affidi a una cache lato client (come Apollo) o a query persistite. Se una cache HTTP standard e gratuita conta molto per te, è un punto a favore di REST.

In sintesi

REST e GraphQL non sono nemici — sono due risposte a «chi decide la forma della risposta?». REST la tiene lato server con endpoint semplici e cacheable; GraphQL la affida al client per query precise e flessibili, al prezzo di una complessità maggiore. Scegli in base alle esigenze di dati dei tuoi client e alla tua propensione alla complessità operativa — e ricorda che puoi usare entrambi là dove ciascuno è adatto.