API REST vs GraphQL: quale scegliere

La scelta tra REST e GraphQL è una delle decisioni architetturali più frequenti nello sviluppo di software moderno. Non esiste una risposta universale: la scelta dipende dal tipo di applicazione, dalla struttura del team e dai requisiti specifici del progetto. Questa guida ti aiuta a prendere la decisione giusta con dati concreti.

Cos’è REST e perché ha dominato per 20 anni

REST (Representational State Transfer) è uno stile architetturale che utilizza gli endpoint HTTP convenzionali per esporre le risorse. Ogni risorsa ha il suo URL, e le operazioni si mappano sui metodi HTTP (GET, POST, PUT, DELETE).

GET    /users          → lista utenti
GET    /users/123      → utente specifico
POST   /users          → crea utente
PUT    /users/123      → aggiorna utente
DELETE /users/123      → elimina utente

REST ha dominato lo sviluppo di API per due decenni perché è semplice da capire, si integra naturalmente con HTTP, è facile da fare il debug con strumenti standard (curl, Postman) e la cache HTTP funziona in modo nativo.

Cos’è GraphQL e perché Facebook lo ha inventato

GraphQL è un linguaggio di query per API sviluppato da Facebook nel 2012 e rilasciato come open source nel 2015. Invece di avere endpoint multipli, GraphQL espone un singolo endpoint dove il client specifica esattamente i dati di cui ha bisogno.

query {
  user(id: "123") {
    name
    email
    posts(last: 5) {
      title
      publishedAt
    }
  }
}

Facebook lo creò per risolvere problemi specifici del feed mobile: la necessità di fetch multipli, l’overfetching di dati non necessari e la difficoltà di mantenere versioni diverse dell’API per client diversi.

Differenze chiave

Fetching dei dati

REST: può soffrire di overfetching (il server restituisce più dati di quelli necessari) e underfetching (servono più richieste per ottenere i dati necessari, problema N+1).

// REST: serve chiamare 3 endpoint
const user = await fetch('/users/123');
const posts = await fetch('/users/123/posts');
const comments = await fetch('/posts/456/comments');

GraphQL: il client specifica esattamente i dati di cui ha bisogno, eliminando overfetching e underfetching.

# GraphQL: una sola query
query {
  user(id: "123") {
    name
    posts {
      title
      comments { text, author { name } }
    }
  }
}

Tipizzazione e schema

GraphQL ha uno schema fortemente tipizzato che serve come contratto esplicito tra frontend e backend. Questo schema è auto-documentante e permette strumenti come GraphQL Playground.

REST non ha uno schema nativo, anche se OpenAPI/Swagger risolve parzialmente questo problema.

Versionamento

REST: il versionamento è esplicito (/v1/users, /v2/users) ma crea debito tecnico nel tempo.

GraphQL: teoricamente non richiede versionamento (aggiungi campi, deprechi i vecchi senza rimuoverli), ma in pratica le breaking changes esistono comunque.

Performance e caching

REST: il caching HTTP funziona perfettamente. Le richieste GET sono cacheable nativamente a livello di CDN.

GraphQL: le query complesse possono essere costose se non ottimizzate. Il caching è più complesso (le query POST non sono cacheable di default). Serve un DataLoader o similar per risolvere il problema N+1.

Quando scegliere REST

API pubbliche e integrazioni di terze parti

Se stai costruendo un’API che verrà consumata da sviluppatori di terze parti, REST è più universale. Tutti sanno come fare una chiamata GET a un endpoint REST. GraphQL richiede conoscenza del linguaggio di query.

Operazioni semplici CRUD

Se la tua API si limita a operazioni di lettura/scrittura su risorse ben definite, REST è perfetto. L’overhead di GraphQL non è giustificato per casi d’uso semplici.

Quando la cache HTTP è critica

Per API pubbliche con alto traffico dove il caching CDN fa la differenza, REST è superiore. Le query GraphQL POST non beneficiano nativamente del caching HTTP.

Microservizi interni

Per la comunicazione tra microservizi dove la semplicità e la standardizzazione sono prioritari, REST (o gRPC per performance) è spesso la scelta migliore.

Quando scegliere GraphQL

Applicazioni con frontend multiple

Se hai un’app mobile e un’app web che necessitano di dati diversi dallo stesso backend, GraphQL elimina la necessità di endpoint specifici per dispositivo o di overfetching su mobile.

Dashboard e applicazioni con dati complessi

Per applicazioni dove le relazioni tra entità sono complesse e i requisiti di dati cambiano frequentemente, GraphQL dà flessibilità senza dover aggiornare l’API del backend ogni volta.

Rapid prototyping con team frontend autonomi

Con GraphQL, il team frontend può iterare sui dati di cui ha bisogno senza attendere modifiche backend. Questo accelera lo sviluppo in team distribuiti.

Feed di dati social o grafici di conoscenza

I dati altamente correlati (tipo social network o knowledge graph) si esprimono naturalmente in GraphQL, dove le relazioni sono first-class citizens.

Il confronto in un progetto reale

Per un’applicazione e-commerce tipica:

L’approccio ibrido: REST + GraphQL

Molte architetture mature usano entrambi:

• GraphQL per le query complesse dell’app principale (feed, dashboard, dati correlati)
• REST per le webhook e le integrazioni di terze parti
• REST per operazioni semplici e ben definite (health checks, file upload)

Strumenti come Apollo Federation permettono di esporre un grafo GraphQL unificato che aggrega API REST esistenti, il che è un ottimo punto di partenza per migrazioni graduali.

Considerazioni pratiche

Curva di apprendimento

REST: bassa. Qualsiasi sviluppatore può capire GET /users/123.

GraphQL: moderata. Richiede capire schemi, resolver, query vs mutation, subscription, DataLoader.

Tooling

REST: eccellente. Swagger/OpenAPI, Postman, curl, librerie in tutti i linguaggi.

GraphQL: molto buono. Apollo (client e server), GraphQL Playground, Hasura, Prisma.

Sicurezza

GraphQL introduce rischi specifici: query di profondità infinita, query di complessità elevata, introspection in produzione. Richiede configurazione aggiuntiva (query depth limiting, complexity analysis).

La nostra raccomandazione

Per la maggior parte dei progetti:

• API interna per app con un frontend: considera GraphQL se le relazioni tra dati sono complesse
• API pubblica o per integrazioni: REST
• Microservizi interni: REST o gRPC
• BFF (Backend for Frontend) per app mobile + web: GraphQL ha un vantaggio chiaro

La decisione migliore è quella che tiene conto delle competenze del tuo team, dei requisiti specifici dell’applicazione e della complessità dei dati. Non scegliere GraphQL per lo hype: sceglilo quando risolve un problema reale che REST non risolve bene.

Hai dubbi su quale architettura API sia più adatta al tuo progetto? Scrivici e analizziamo il tuo caso concreto.