REST vs GraphQL: confronto pratico per scegliere la tua API

Due approcci allo stesso problema

REST e GraphQL risolvono entrambi lo stesso problema fondamentale: come fa un client (un browser, un'app mobile, un altro servizio) a richiedere dati a un server? Ma lo risolvono in modi molto diversi, e scegliere tra loro ha conseguenze reali sulle prestazioni, l'esperienza dello sviluppatore e la manutenibilita a lungo termine della tua applicazione.

REST e stato il paradigma API dominante dalla meta degli anni 2000. GraphQL e stato sviluppato da Facebook nel 2012 e reso open-source nel 2015. Entrambi sono ampiamente usati in produzione oggi, e nessuno dei due sta scomparendo. La domanda non e quale sia "migliore" in astratto, ma quale si adatti alla tua situazione specifica.

Come funziona REST

REST (Representational State Transfer) organizza la tua API attorno alle risorse. Ogni risorsa (un utente, un prodotto, un ordine) ha un URL e interagisci con essa usando metodi HTTP standard.

Concetti fondamentali

• Risorse: tutto e una risorsa con un URL unico. /users/42 e l'utente con ID 42. /products e la collezione di tutti i prodotti.
• Metodi HTTP: GET legge, POST crea, PUT/PATCH aggiorna, DELETE cancella.
• Stateless: ogni richiesta contiene tutte le informazioni necessarie al server.
• Codici di stato HTTP standard: 200 per successo, 404 per non trovato, 401 per non autorizzato.

Esempio: recupero di un profilo utente

Richiesta:

GET /api/users/42

Risposta (200 OK):

{"id": 42, "name": "Maria Rossi", "email": "maria@example.com", "department": "Engineering", "role": "Lead Developer", "joined": "2019-03-15", "avatar_url": "/avatars/42.jpg", "phone": "+41 91 123 4567", "address": {"street": "Via Nassa 12", "city": "Lugano", "zip": "6900", "country": "CH"}, "preferences": {"language": "it", "theme": "dark", "notifications": true}}

Il server restituisce la risorsa utente completa. Il client riceve tutto cio che il server decide di includere, che ne abbia bisogno o meno.

Esempio: recupero degli ordini di un utente

Per ottenere gli ordini dello stesso utente, serve una seconda richiesta:

GET /api/users/42/orders

Due richieste per visualizzare una pagina che mostra un profilo utente con i suoi ordini recenti.

Come funziona GraphQL

GraphQL adotta un approccio fondamentalmente diverso. Invece di endpoint multipli che restituiscono strutture dati fisse, c'e un singolo endpoint. Il client specifica esattamente quali dati gli servono in una query, e il server restituisce precisamente quei dati.

Concetti fondamentali

• Endpoint singolo: tutte le richieste vanno a un URL (tipicamente /graphql).
• Query guidate dal client: il client definisce forma e contenuto della risposta.
• Schema tipizzato: l'API ha uno schema che definisce tutti i tipi, campi e relazioni disponibili.
• Dati annidati: i dati correlati possono essere recuperati in una singola query attraversando le relazioni.

Esempio: recupero dello stesso profilo con ordini

Richiesta:

POST /graphql

{"query": "{ user(id: 42) { name email department orders(last: 5) { id date total status } } }"}

Risposta (200 OK):

{"data": {"user": {"name": "Maria Rossi", "email": "maria@example.com", "department": "Engineering", "orders": [{"id": 101, "date": "2022-04-10", "total": 250.00, "status": "shipped"}, {"id": 98, "date": "2022-04-01", "total": 89.90, "status": "delivered"}]}}}

Una sola richiesta. La risposta contiene esattamente i campi richiesti. Niente telefono, indirizzo, preferenze o avatar.

Il problema dell'over-fetching e dell'under-fetching

Questo e il problema centrale che ha motivato la creazione di GraphQL.

Over-fetching

Il server restituisce piu dati di quelli necessari al client. Nell'esempio REST, per visualizzare nome ed email di un utente su una dashboard, ricevi comunque telefono, indirizzo, preferenze e avatar. Su una connessione veloce i byte extra sono trascurabili. Su una connessione mobile, trasmettere dati non necessari spreca banda e rallenta l'esperienza.

Under-fetching

Il problema opposto: il server non restituisce abbastanza dati in una singola risposta, costringendo il client a fare richieste sequenziali multiple. Una pagina reale potrebbe richiedere cinque o sei chiamate API separate per renderizzarsi completamente.

L'under-fetching porta a richieste a cascata: il client fa la richiesta A, aspetta la risposta, poi fa la richiesta B (che dipende dai dati di A), aspetta quella risposta, poi fa la richiesta C. Ogni round trip aggiunge latenza.

GraphQL risolve entrambi i problemi. Il client chiede esattamente cio che gli serve (niente over-fetching) e lo ottiene tutto in una richiesta (niente under-fetching).

Quando usare REST

REST non e obsoleto. Per molti casi d'uso, e la scelta migliore.

Operazioni CRUD semplici

Se la tua API e principalmente creare, leggere, aggiornare e cancellare risorse con strutture dati semplici, il modello orientato alle risorse di REST si adatta naturalmente al tuo dominio.

API pubbliche

Se stai costruendo un'API che sviluppatori esterni consumeranno, REST e generalmente piu facile da capire e usare. La curva di apprendimento e piu bassa e gli strumenti di documentazione (Swagger/OpenAPI) sono maturi.

Caching

Gli URL basati sulle risorse di REST funzionano naturalmente con il caching HTTP. GET /api/products/42 puo essere cachato a ogni livello: browser, CDN, reverse proxy. GraphQL usa richieste POST a un singolo endpoint, rendendo il caching HTTP piu difficile.

Per i siti web pubblici dove il caching e fondamentale per prestazioni e costi (come quelli che costruiamo in Envestis), REST o anche pagine statiche pre-renderizzate servite da CDN superano GraphQL nella maggior parte degli scenari. Vedi il nostro articolo su velocita del sito e impatto sul business.

Upload di file e download

REST gestisce i dati binari naturalmente. GraphQL richiede workaround per la gestione dei file.

Comunicazione tra microservizi

Per la comunicazione servizio-a-servizio dove ogni servizio ha esigenze dati ben definite, la semplicita di REST e un vantaggio.

Quando usare GraphQL

Relazioni dati complesse

Quando il tuo modello dati ha relazioni profonde (utenti con ordini che contengono prodotti che appartengono a categorie), la struttura di query annidata di GraphQL permette ai client di attraversare queste relazioni efficientemente.

Client frontend multipli

Se hai un'app web, un'app mobile e forse un'integrazione partner che consumano la stessa API, le query guidate dal client di GraphQL significano che ogni client puo richiedere esattamente i dati di cui ha bisogno.

Iterazione frontend rapida

Quando il frontend cambia frequentemente, GraphQL permette agli sviluppatori frontend di modificare i requisiti dati senza modifiche al backend.

Applicazioni mobile

Le connessioni mobili sono spesso piu lente e costose. La capacita di GraphQL di recuperare esattamente cio che serve in una singola richiesta riduce latenza e consumo di dati.

Aggregazione dati da fonti multiple

GraphQL puo servire come livello API unificato che aggrega dati da servizi backend multipli, database o API di terze parti.

Considerazioni sulle prestazioni

Prestazioni di rete

GraphQL vince tipicamente sulle prestazioni di rete grazie ai round trip ridotti e ai payload piu piccoli. Questo vantaggio e piu pronunciato su connessioni ad alta latenza.

Prestazioni del server

Le query GraphQL possono essere computazionalmente costose lato server. Un client puo costruire una query che attraversa relazioni profonde e richiede grandi quantita di dati. Senza protezioni, questo puo sovraccaricare il server.

Caching

REST ha un chiaro vantaggio nel caching a livello HTTP. CDN, cache del browser e reverse proxy funzionano nativamente con il modello basato su URL di REST.

Implicazioni per la sicurezza

Rate limiting

Le API REST sono semplici da limitare: conti le richieste per endpoint per periodo. Il rate limiting di GraphQL e piu complesso perche una singola richiesta puo fare il lavoro di molte richieste REST. Devi considerare la complessita della query, non solo il conteggio delle richieste.

Attacchi di profondita e complessita delle query

GraphQL introduce un rischio che REST non ha: query malevole. Un client puo costruire una query profondamente annidata che forza il server a eseguire milioni di query al database. Ogni API GraphQL ha bisogno di protezioni: profondita massima delle query, scoring di complessita e timeout.

Autorizzazione

L'autorizzazione REST e tipicamente per-endpoint. L'autorizzazione GraphQL deve essere per-campo o per-tipo, il che e piu granulare ma anche piu complesso da implementare.

Introspezione

L'introspezione di GraphQL permette ai client di interrogare lo schema stesso, scoprendo tutti i tipi e campi disponibili. Utile in sviluppo, deve essere disabilitata in produzione per le API pubbliche.

Confronto degli strumenti

Categoria	REST	GraphQL
Documentazione API	Swagger/OpenAPI (maturo)	GraphiQL, GraphQL Playground (auto-documentante)
Testing API	Postman, Insomnia, curl	Postman, Insomnia, Apollo Studio
Librerie client	Axios, Fetch API, qualsiasi client HTTP	Apollo Client, urql, Relay
Framework server	Express, FastAPI, Spring Boot	Apollo Server, Mercurius, Hasura
Generazione codice	OpenAPI Generator	GraphQL Code Generator
Monitoraggio	Strumenti APM standard	Apollo Studio, Stellate

Un framework decisionale

Rispondi a queste domande sul tuo progetto:

1. Quanto e complesso il tuo modello dati? Semplice: REST. Complesso con relazioni profonde: GraphQL.
2. Quanti tipi di client servi? Uno o due con esigenze simili: REST. Multipli con esigenze diverse: GraphQL.
3. Quanto e rilevante il caching? Il caching HTTP e prioritario: REST. Il caching a livello applicazione e accettabile: entrambi.
4. Qual e l'esperienza del tuo team? Considera la curva di apprendimento. GraphQL richiede comprendere schema, resolver, ottimizzazione query e nuovi pattern di sicurezza.
5. E un'API pubblica o interna? Pubblica per sviluppatori esterni: REST. Interna per i tuoi frontend: decidi in base ai fattori sopra.

L'approccio ibrido

Non devi sceglierne uno esclusivamente. Molti sistemi in produzione usano entrambi:

• REST per CRUD semplice e API pubbliche dove contano caching e semplicita.
• GraphQL come BFF (Backend for Frontend) che aggrega dati da microservizi REST.
• REST per upload file e webhook, GraphQL per le query dati.

GitHub, per esempio, mantiene sia un'API REST (v3) che un'API GraphQL (v4).

L'importante e prendere una decisione consapevole basata sui tuoi requisiti. Se stai pianificando un'architettura API per un nuovo progetto e vuoi un secondo parere, il nostro team di sviluppo a Lugano e disponibile a valutare i tuoi requisiti e consigliare l'approccio giusto.

Riepilogo: quando usare cosa

Scenario	Raccomandazione
Applicazione CRUD semplice	REST
API pubblica per sviluppatori terzi	REST
Sito ricco di contenuti con CDN	REST o generazione statica
Dati complessi con relazioni profonde	GraphQL
Client frontend multipli (web + mobile)	GraphQL
Iterazione frontend rapida	GraphQL
Sottoscrizioni in tempo reale	GraphQL (con subscriptions)
Livello di aggregazione microservizi	GraphQL come BFF
Upload di file	REST
Webhook	REST