Se negli ultimi anni ti sei avvicinato allo sviluppo di applicazioni web o mobile, è probabile che tu abbia sentito parlare di “REST API” e “GraphQL” praticamente ovunque. Non si tratta di due buzzword a caso, ma di due approcci profondamente diversi nel modo in cui un’applicazione espone e scambia dati con il mondo esterno. In altre parole, se pensiamo a un’app come a una città, REST e GraphQL sono due sistemi stradali diversi: entrambi ti portano a destinazione, ma lo fanno con regole, percorsi e infrastrutture differenti.
REST (che sta per Representational State Transfer) è un’architettura concettualizzata all’inizio degli anni 2000 da Roy Fielding, uno dei padri fondatori del web moderno. L’idea era semplice ma potente: definire un insieme di principi e convenzioni che permettessero di creare interfacce coerenti, scalabili e facili da capire, basate su risorse identificate da URL e manipolate attraverso metodi HTTP standard come GET, POST, PUT e DELETE. Questa filosofia ha guidato lo sviluppo di innumerevoli API negli ultimi due decenni, diventando di fatto uno standard de facto.
Poi, nel 2015, è arrivato GraphQL, un linguaggio di query per API creato in casa Facebook per risolvere un problema ben preciso: dare ai client la possibilità di chiedere esattamente i dati di cui hanno bisogno, né più né meno, evitando di sovraccaricare la rete o di fare troppe chiamate. Con un unico endpoint e una sintassi chiara e tipizzata, GraphQL ha introdotto un paradigma completamente nuovo, soprattutto in contesti in cui il frontend deve comunicare con molte fonti dati diverse o in cui la flessibilità è un requisito primario.
Oggi, sviluppatori e team si trovano sempre più spesso a un bivio: seguire la strada collaudata di REST, con la sua prevedibilità e maturità, o abbracciare la modernità di GraphQL, con la sua flessibilità e il controllo granulare sui dati. In questo articolo esploreremo le differenze fondamentali tra questi due approcci, partendo dai loro principi base, per capire non solo come funzionano, ma anche perché uno potrebbe essere più adatto dell’altro in un determinato contesto.
Cos’è REST API
REST, acronimo di Representational State Transfer, non è né un framework né un protocollo, ma un insieme di principi architetturali per progettare interfacce di comunicazione tra sistemi. Si fonda sull’uso coerente del protocollo HTTP, sfruttando concetti già presenti nel web come gli URL, i metodi HTTP, i codici di stato, le intestazioni e i formati di rappresentazione dei dati, tipicamente JSON o XML.
L’idea alla base è semplice: ogni elemento gestito dall’API viene trattato come una “risorsa” e deve poter essere identificato in maniera univoca attraverso un URI. Per esempio, una chiamata come:
GET /api/users/42
permette di ottenere le informazioni relative all’utente con ID 42.
Il modello REST incoraggia anche un utilizzo semantico dei metodi HTTP. Il
verbo della richiesta indica già l’operazione che si vuole eseguire: GET per
leggere dati, POST per creare nuove risorse, PUT o PATCH per modificarle,
DELETE per rimuoverle. Questo approccio rende l’API autoesplicativa,
riducendo la necessità di documentazione e favorendo la comprensione immediata.
Un altro aspetto fondamentale è la natura stateless della comunicazione. Ogni richiesta contiene tutte le informazioni necessarie al server per essere processata, senza che questo mantenga memoria dello stato della sessione tra una chiamata e l’altra. Questo semplifica l’architettura e ne migliora la scalabilità, ma implica che sia il client a dover gestire eventuali stati o sessioni.
In REST, la risorsa vera e propria non è ciò che viene inviato, ma la sua
rappresentazione. Lo stesso utente, ad esempio, potrebbe essere restituito in
JSON per un’applicazione web moderna o in XML per integrarsi con un sistema
legacy. Infine, i codici di stato HTTP sono parte integrante del linguaggio
dell’API: un 200 OK comunica un esito positivo, 201 Created segnala la
creazione di una nuova risorsa, 404 Not Found indica che la risorsa non
esiste e così via.
Struttura tipica di un endpoint REST
Un’API REST ben progettata organizza i propri endpoint attorno a entità logiche, mantenendo una struttura chiara e coerente. Immaginiamo un’applicazione di blogging: gli articoli possono essere gestiti attraverso endpoint come questi:
| Operazione | Metodo HTTP | Endpoint | Descrizione |
| --------------------------- | ----------- | ----------------- | --------------------------------- |
| Leggere tutti gli articoli | GET | /api/posts | Restituisce la lista di articoli |
| Creare un nuovo articolo | POST | /api/posts | Crea un articolo |
| Leggere un articolo singolo | GET | /api/posts/{id} | Restituisce i dettagli di un articolo |
| Aggiornare un articolo | PUT/PATCH | /api/posts/{id} | Modifica un articolo |
| Eliminare un articolo | DELETE | /api/posts/{id} | Rimuove un articolo |
Questo schema, replicato per tutte le entità, rende REST molto intuitivo sia per chi sviluppa sia per chi mantiene il codice.
Over-fetching e under-fetching
Nonostante la sua diffusione e semplicità concettuale, REST presenta alcune limitazioni ricorrenti. Due delle più note sono l’over-fetching e l’under-fetching.
Il primo si verifica quando il client riceve più informazioni di quelle
realmente necessarie. Ad esempio, se l’endpoint /api/users/42 restituisce
l’intero profilo dell’utente ma al frontend serve solo il nome, la risposta
conterrà dati inutili, aumentando il traffico e rallentando i tempi di
risposta.
Il secondo problema, l’under-fetching, è l’esatto opposto: la risposta non contiene tutte le informazioni utili e il client è costretto a fare più richieste per completare il dato. Per esempio, per mostrare un profilo utente insieme ai suoi post più recenti, il frontend potrebbe dover fare prima una chiamata per ottenere l’utente e poi un’altra per recuperare i post.
In contesti semplici queste inefficienze sono tollerabili, ma in applicazioni complesse o in ambienti con connessioni lente possono diventare un ostacolo concreto. È proprio in questo ambito che GraphQL ha introdotto un approccio radicalmente diverso, pensato per risolvere questi limiti intrinseci di REST.
Cos’è GraphQL
GraphQL nasce nel 2012 all’interno di Facebook come risposta a un problema molto pratico: la necessità di ottimizzare lo scambio di dati tra client e server in applicazioni complesse, in particolare quelle mobili, dove la banda e la latenza sono risorse preziose. Pubblicato come progetto open source nel 2015, GraphQL non è un framework né un protocollo, ma un linguaggio di query e un runtime per interrogare i dati. La sua filosofia ruota attorno a un concetto chiave: lasciare al client il controllo esatto di quali dati ottenere e in quale struttura, riducendo al minimo sia l’over-fetching che l’under-fetching tipici delle API REST.
A differenza di REST, che espone molteplici endpoint (uno per ogni risorsa o operazione), GraphQL si basa quasi sempre su un singolo endpoint attraverso il quale passano tutte le richieste. Questo endpoint riceve query strutturate in un linguaggio dichiarativo che descrive i dati desiderati, e il server restituisce esattamente quegli stessi dati, né più né meno.
Schema: il contratto tra client e server
Il cuore di GraphQL è lo schema: una definizione tipizzata di tutte le entità disponibili, delle relazioni tra di esse e delle operazioni consentite. Lo schema agisce come un contratto formale tra client e server, ed è composto principalmente da tre tipologie di operazioni:
- Query – per leggere dati.
- Mutation – per modificare dati (creare, aggiornare, eliminare).
- Subscription – per ricevere aggiornamenti in tempo reale quando i dati cambiano.
Ad esempio, una query per ottenere il nome e l’email di un utente insieme ai titoli dei suoi ultimi tre post potrebbe essere:
query {
user(id: 42) {
name
email
posts(limit: 3) {
title
}
}
}
La risposta JSON conterrà esattamente quelle proprietà, nella struttura richiesta:
{
"data": {
"user": {
"name": "Alice",
"email": "alice@example.com",
"posts": [
{ "title": "Introduzione a GraphQL" },
{ "title": "Ottimizzare le API" },
{ "title": "GraphQL vs REST" }
]
}
}
}
La centralità del singolo endpoint
L’uso di un solo endpoint rende GraphQL molto diverso da REST sotto il profilo architetturale. Non esiste un mapping rigido “risorsa = URL”, e la logica di recupero dei dati è demandata alla struttura della query. Questo approccio offre una flessibilità enorme, ma richiede anche un’implementazione server più sofisticata, capace di interpretare la query, eseguire le operazioni necessarie e aggregare i dati da una o più fonti (database, API esterne, microservizi).
In sintesi, GraphQL ribalta il paradigma di REST: invece di definire cosa il server decide di esporre e il client deve adattarsi, è il client a chiedere esattamente ciò che gli serve, e il server risponde di conseguenza. Questo elimina gran parte delle inefficienze nella trasmissione dei dati, ma introduce anche nuove sfide, ad esempio nella complessità di caching e sicurezza.
Conclusione
REST e GraphQL non sono in competizione “per la vita”, ma due modi diversi di pensare e costruire API. REST ha dalla sua la semplicità, la familiarità e un’ampia diffusione: segue principi chiari, si appoggia agli standard HTTP e funziona bene in un’enorme varietà di scenari. GraphQL, invece, nasce per risolvere problemi specifici di efficienza e flessibilità nella gestione dei dati, permettendo ai client di ottenere esattamente ciò di cui hanno bisogno in una singola richiesta.
Quello che emerge è che la scelta non può basarsi solo sulla moda tecnologica o sulla velocità promessa da un benchmark, ma deve tenere conto del contesto: complessità del dominio, necessità di ottimizzare il traffico dati, tipologia di client, competenze del team e capacità di gestire la manutenzione nel tempo.
Nella prossima parte ci spingeremo oltre la teoria, confrontando i due approcci dal punto di vista tecnico: vedremo pro e contro di ciascuno, differenze nell’implementazione e casi d’uso concreti, così da poter prendere decisioni consapevoli e mirate.
