Hai un e-commerce o un gestionale con più frontend: web, app mobile, integrato con marketplace esterni. Con le REST API classiche ogni nuovo view richiede un endpoint nuovo, e spesso arriva un payload troppo pieno o troppo leggero. Il cliente vuole una dashboard con ordini, cliente e storico pagamenti in una sola schermata? Fai tre chiamate REST e poi assembli lato client. Over-fetching, under-fetching, e un mal di testa a manutenere.
GraphQL risolve con un unico endpoint e una specifica chiara su cosa si può chiedere e come. Noi, di Meteora Web, lo usiamo da anni nei progetti che richiedono flessibilità sui dati. Lo abbiamo scelto per gestire piattaforme con molti tipi di relazione (prodotti, varianti, ordini, clienti, fornitori) e per dare ai frontend il potere di chiedere solo quello che serve. Ma per usarlo bene devi padroneggiare i suoi tre pilastri: Schema, Query, Mutation e Subscription. In questa guida ti portiamo dalla teoria alla pratica, con codice che puoi copiare e testare subito.
Che cos'è lo Schema in GraphQL e perché è il cuore del contratto API?
Nelle REST API il contratto è implicito: ogni endpoint restituisce una struttura JSON definita dal back-end. Il frontend deve adattarsi. GraphQL rovescia il modello: il server espone uno schema che dichiara esattamente quali tipi di dati esistono, quali relazioni hanno e quali operazioni (query, mutation, subscription) sono disponibili. Il client può consultare lo schema (introspection) e costruire richieste precise.
Un esempio concreto: immagina di gestire un negozio di abbigliamento (noi, con Hibrido Abbigliamento, sappiamo bene come funziona il retail). Lo schema GraphQL potrebbe contenere un tipo Prodotto con campi come id, nome, prezzo, varianti (taglia, colore, giacenza). Poi un tipo Ordine collegato a Cliente e Prodotto. In REST avresti endpoint separati /products, /products/:id, /orders, /orders/:id. In GraphQL una sola richiesta può ottenere tutti i dati annidati.
Sponsored Protocol
# schema.graphql esempio per un negozio
type Prodotto {
id: ID!
nome: String!
prezzo: Float!
descrizione: String
varianti: [Variante!]!
}
type Variante {
taglia: String
colore: String
giacenza: Int!
}
type Cliente {
id: ID!
nome: String!
email: String!
}
type Ordine {
id: ID!
cliente: Cliente!
prodotti: [Prodotto!]!
totale: Float!
data: String!
}
type Query {
prodotti(categoria: String, primo: Int): [Prodotto!]!
prodotto(id: ID!): Prodotto
ordini(clienteId: ID!): [Ordine!]!
}
type Mutation {
creaProdotto(input: InputProdotto!): Prodotto
aggiornaProdotto(id: ID!, input: InputProdotto!): Prodotto
cancellaProdotto(id: ID!): Boolean!
}
input InputProdotto {
nome: String!
prezzo: Float!
descrizione: String
varianti: [InputVariante!]
}
input InputVariante {
taglia: String
colore: String
giacenza: Int!
}Ogni volta che guardi lo schema, sai esattamente cosa puoi chiedere e cosa restituirà il server. Nessuna sorpresa. Noi lo usiamo anche per la documentazione automatica: strumenti come GraphQL Playground o Apollo Studio generano una documentazione interattiva dallo schema. Il frontend non deve più aspettare che il back-end aggiunga un nuovo campo a un endpoint: se il tipo esiste, può già essere richiesto.
Perché i tipi personalizzati (scalar, enum, input) rendono lo schema robusto
GraphQL fornisce tipi built-in (String, Int, Float, Boolean, ID). Ma la vera potenza è nei tipi personalizzati. Un enum come Categoria (ABBIGLIAMENTO, ACCESSORI, SCARPE) garantisce che i valori siano sempre validi. Un input type permette di passare oggetti strutturati nelle mutation, evitando parametri sparsi. Noi, in un progetto per un cliente di Sicilia, abbiamo definito un tipo Indirizzo riutilizzato in mutazioni di creazione e aggiornamento: pulizia e coerenza.
Sponsored Protocol
Come si scrivono le Query per ottenere solo i dati che servono?
Una query in GraphQL è una richiesta che descrive esattamente la forma della risposta. Non c'è più il problema dell'over-fetching (ricevi 50 campi quando ne servono 3) né dell'under-fetching (devi fare più chiamate per avere dati correlati).
# Query di esempio: ultimi 5 prodotti della categoria "abbigliamento" con varianti
query {
prodotti(categoria: "abbigliamento", primo: 5) {
id
nome
prezzo
varianti {
taglia
giacenza
}
}
}Questa query restituisce solo id, nome, prezzo e le varianti. Se il frontend richiede anche la descrizione, basta aggiungere il campo — senza modificare il back-end. Il controllo passa al client: una rivoluzione per team che sviluppano web e mobile separatamente.
Alias, frammenti e variabili
- Alias – permetti di eseguire due query dello stesso tipo con nomi diversi:
prodottiInOfferta: prodotti(categoria: "offerta") { ... }. - Frammenti – riutilizzare un set di campi:
fragment CampiProdotto on Prodotto { id nome prezzo }. - Variabili – rendi le query parametriche senza hard-coding. Il client passa un JSON con le variabili.
Se arrivi da REST, nota: non esiste più la gestione di endpoint diversi per filtri diversi. l'intera logica è nell'argomento della query.
Sponsored Protocol
Quale differenza tra Mutation e Query nel flusso operativo?
Le mutation servono a modificare i dati (creare, aggiornare, cancellare). La differenza fondamentale con la query è che le mutation vengono eseguite in sequenza garantita (se invii più mutation, la prima finisce prima della seconda). Inoltre è buona pratica che una mutation restituisca i dati modificati, così il frontend può aggiornare la cache locale.
# Mutation: crea un nuovo prodotto
mutation CreaProdotto($input: InputProdotto!) {
creaProdotto(input: $input) {
id
nome
prezzo
varianti {
taglia
giacenza
}
}
}Variabili da passare:
{
"input": {
"nome": "Maglia a righe",
"prezzo": 34.90,
"varianti": [
{"taglia": "M", "colore": "blu", "giacenza": 10}
]
}
}Noi, di Meteora Web, vediamo spesso errori di progettazione quando si lascia la mutation senza ritorno. Se la mutation restituisce solo un booleano, il frontend deve rifare una query per avere l'oggetto aggiornato – due round trip inutili. Restituisci sempre il tipo modificato o almeno i campi che potrebbero essere cambiati.
Pattern per gestire errori nelle mutation
In REST, spesso si usa lo status code 400/500 e un messaggio. In GraphQL, le mutation possono restituire un tipo unione (successo + errore) per avere dati strutturati. Esempio:
type Mutation {
creaProdotto(input: InputProdotto!): RisultatoProdotto
}
type RisultatoProdotto {
successo: Boolean!
prodotto: Prodotto
errore: Errore
}
type Errore {
codice: String!
messaggio: String!
}Così il frontend sa sempre se l'operazione è riuscita, e in caso di errore ha un oggetto parsabile. Non affidarti solo ai messaggi di errore a livello di esecuzione GraphQL (tipo errors array), usa tipi personalizzati per logiche di business.
Sponsored Protocol
Come e quando usare le Subscription per aggiornamenti in tempo reale?
Le subscription permettono al server di inviare dati al client quando si verifica un evento. Dietro le quinte usano WebSocket (o altri protocolli). Sono ideali per notifiche live, chat, aggiornamenti di stato ordini o cruscotti in tempo reale.
# Subscription: ricevi notifica quando viene creato un nuovo ordine
subscription {
ordineCreato {
id
totale
cliente {
nome
email
}
}
}Il client si sottoscrive e rimane in ascolto. Quando un ordine viene creato (tramite una mutation creaOrdine), il server invia i dati a tutti i client sottoscritti. Noi abbiamo implementato una subscription per un cliente con un gestionale di magazzino: quando un prodotto scende sotto la soglia minima, il responsabile riceve un avviso istantaneo senza ricaricare la pagina.
Quando non usare subscription
- Se l'aggiornamento può essere fatto con un polling periodico (es. ogni 30 secondi) e non serve reattività immediata.
- Se l'infrastruttura non supporta WebSocket (alcuni hosting condivisi o ambienti serverless hanno limitazioni).
- Se il numero di eventi è molto alto e il client ne riceve troppi gestibili con una semplice query periodica.
In ogni caso, implementa subscription solo per eventi sporadici e critici. Per aggiornamenti continui (es. prezzi in tempo reale da un mercato), valuta Flusso WebSocket dedicato o Server-Sent Events.
GraphQL vs REST per il tuo prossimo progetto — quando conviene?
GraphQL non è la risposta a tutto. Lo usiamo quando:
- Il frontend ha esigenze di dati variabili (mobile, web, terze parti).
- Il modello dati è fortemente interconnesso (es. e-commerce, CRM, gestionali).
- Serve documentazione automatica e versioning senza moltiplicare endpoint.
REST resta più semplice per progetti con azioni CRUD lineari, poco overlap tra frontend, e dove si sfruttano caching HTTP efficiente (Varnish, CDN). Noi consigliamo di valutare il team: se il frontend ha già familiarità con GraphQL e il backend può dedicare tempo al setup, è un investimento che paga. Altrimenti, parti da REST e aggiungi GraphQL come layer esterno con Apollo Federation o altro.
Sponsored Protocol
Cosa fare adesso
- Esplora lo schema del tuo progetto attuale (se già usi GraphQL) o crea uno schema minimo per un dominio che conosci (es. un blog: Post, Autore, Commento). Scrivilo in un file
.graphqle validalo con GraphQL Code Generator o Apollo VS Code. - Testa query con variabili su GraphQL Playground o Apollo Studio. Simula un caso reale: ottenere gli ultimi 10 ordini di un cliente con i prodotti e totali.
- Integra una mutation nel tuo frontend (Apollo Client o Relay). Prova a creare un oggetto e a visualizzare l'ID restituito.
- Se hai bisogno di tempo reale, aggiungi una subscription per eventi di notifica (es. nuovo messaggio, ordine ricevuto). Verifica che il server supporti WebSocket.
- Leggi la documentazione ufficiale su graphql.org/learn/schema per approfondire ogni tipo.
Noi, di Meteora Web, restiamo a disposizione per supportare il tuo team. Nel nostro articolo pillar su API REST e GraphQL trovi confronti e scelte architetturali più ampie. Ma se hai un progetto concreto, parlaci: valutiamo insieme se GraphQL è la strada giusta per i tuoi numeri.
