GraphQL: query language per API
Risposta breve
GraphQL è un linguaggio per interrogare API, con un runtime lato server che opera su uno schema tipizzato. Il client decide quali campi ottenere, compresi dati collegati, in un'unica operazione.
Punti chiave
- Il client richiede solo i campi necessari, riducendo dati inutili.
- Lo schema definisce tipi, campi, relazioni e operazioni disponibili.
- Query legge dati, mutation modifica dati, subscription aggiorna in tempo reale.
- La risposta segue la struttura richiesta e può contenere dati parziali con errori.
GraphQL è un linguaggio per interrogare API, eseguito da un runtime lato server. È pensato per chi sviluppa interfacce: la richiesta dei dati segue la struttura delle viste e il loro uso. Un servizio espone le operazioni disponibili ai client, che scelgono i campi da ricevere senza richiedere altro.
Cos'è GraphQL e perché è diverso
GraphQL serve a interrogare e modificare dati, indicando esattamente cosa recuperare o cambiare. Un server può rispondere a una query combinando dati da fonti diverse in un unico grafo. Il linguaggio non dipende da un database o da un motore di archiviazione particolare.
Le query seguono la struttura dell'interfaccia, così la richiesta ha la stessa forma della risposta. I frammenti permettono di definire i bisogni di dati di ogni componente vicino al componente e di soddisfarli con una sola query. Questo rende naturale richiedere dati che corrispondono alla forma della risposta.
Schema, tipi e operazioni
GraphQL definisce dati e operazioni dell'API tramite schema, tipi e tipi di operazione radice. Lo schema descrive tipi, campi, relazioni e operazioni con il Schema Definition Language. Query è obbligatorio; Mutation e Subscription sono facoltativi.
I tipi descrivono strutture e valori: scalari, oggetti, enum, interfacce, union e oggetti di input. Il punto esclamativo segnala che un campo non può essere null. Questa tipizzazione forte rende il contratto dell'API esplicito e verificabile.
Query, mutation e subscription
Le query servono a leggere dati dal server GraphQL. Il client indica i campi necessari, anche dati correlati previsti dallo schema. Le mutation modificano dati, ad esempio creando, aggiornando o eliminando record; il comportamento dipende dal server. Le subscription forniscono aggiornamenti in tempo reale se implementate.
In un'API di blog, il client può aver bisogno di un post e dei dati dell'autore. Con endpoint fissi possono servire più richieste se post e autore sono separati. GraphQL può ottenere entrambi in una query se lo schema definisce la relazione.
La query richiede il post con id 1, includendo titolo, contenuto e i campi nome ed email dell'autore. La risposta segue la struttura dei campi richiesti, permettendo di recuperare dati correlati in una sola operazione.
Come il server esegue una richiesta
I resolver alimentano l'esecuzione GraphQL. Il server elabora la query e restituisce i dati per ogni campo. Se si verifica un errore durante l'esecuzione, la risposta può contenere sia dati parziali sia dettagli dell'errore, a seconda dell'errore e della nullabilità dello schema.
Un'API sana parte da uno schema ben governato. I modelli di proprietà dello schema includono approcci centralizzati, federati e ibridi. I processi di revisione e la validazione automatica aiutano a mantenere lo schema coerente, sicuro e facile da far evolvere.
GraphQL rispetto a endpoint fissi
| Aspetto | Endpoint fissi | GraphQL |
|---|---|---|
| Numero richieste | Spesso più richieste per dati correlati | Una richiesta può includere dati correlati |
| Controllo campi | Definito dal server | Definito dal client |
| Schema | Non obbligatorio | Tipizzato e pubblicato |
| Evoluzione | Spesso versioni | Aggiunta campi senza rompere client |
GraphQL non sostituisce automaticamente ogni API. Ha senso quando il client ha bisogno di campi variabili, dati correlati e controllo fine sul payload. Endpoint fissi possono essere più semplici per operazioni CRUD prevedibili o per integrazioni con contratti stabili.
Frammenti, variabili ed errori
I frammenti restano utili per raccogliere i requisiti di dati dei componenti in un'unica query. Le variabili rendono le query riutilizzabili senza riscrivere la struttura. Per gli errori, si possono usare errori di primo livello o errori come dati, scegliendo in base a guasti eccezionali o a esiti attesi.
Per i file, la gestione degli upload può essere integrata come mutation. Questo mantiene il modello di operazioni coerente: lettura con query, modifica con mutation, aggiornamento continuo con subscription.
Servire GraphQL su HTTP
GraphQL opera spesso su HTTP. La progettazione include metodo, intestazioni, codici di stato e struttura dell'endpoint. Poiché l'API può descriversi, gli strumenti e le librerie client possono interrogare lo schema per conoscere tipi e capacità disponibili.
Questo rende GraphQL una piattaforma per costruire strumenti comuni e librerie client. Le guide di best practice coprono anche il passaggio da endpoint RESTful a pensiero basato su grafo, allineando schema, logica di business e sistemi legacy.
Governance dello schema
La governance dello schema include proprietà, revisione e controlli automatici. Un processo di revisione aiuta a mantenere coerenza e sicurezza mentre il team cresce. Le API flessibili richiedono disciplina: aggiungere campi è facile, ma rimuovere o cambiare significato di campi esistenti può rompere i client.
Quando ha senso usarlo
GraphQL ha senso per prodotti con molte viste, client diversi e dati correlati. Permette di richiedere solo i campi necessari e di recuperare dati correlati in una sola operazione. Se il dominio è semplice e le risposte sono stabili, un'API con endpoint fissi può essere sufficiente.
Per contesto sui linguaggi vedi Storia dei linguaggi di programmazione: origini e evoluzione; per concetti dichiarativi vedi Programmazione funzionale per principianti: cos'è?; per sistemi che descrivono capacità vedi Modello linguistico di grandi dimensioni: definizione.
Altre domande frequenti
GraphQL è un database?
No, è un linguaggio di query per API e un runtime lato server; non è legato a un database specifico.
Quali operazioni supporta?
Query per leggere, mutation per modificare e subscription per aggiornamenti in tempo reale quando implementate.
GraphQL restituisce sempre tutti i campi?
No, il client sceglie i campi da ricevere a livello di campo.
Come gestisce gli errori?
La risposta può contenere dati parziali e dettagli di errore, a seconda dell'errore e della nullabilità dello schema.
Pagine correlate
- Rendering lato client vs lato server: differenze
Il rendering lato client genera l'HTML nel browser tramite JavaScript, mentre il rendering lato server produce la pagina completa sul server prima dell'invio. La scelta incide su tempi di caricamento iniziale, indicizzazione, costi infrastrutturali e interattività. Un approccio ibrido può combinare un primo caricamento server-side con interazioni client-side.
- Cos'è CORS: funzionamento e sicurezza web
CORS (Cross-Origin Resource Sharing) definisce uno standard regolato da intestazioni HTTP che permette ai server di autorizzare domini terzi ad accedere ai propri contenuti. Estende in modo controllato la Same-Origin Policy integrata nei browser, autorizzando chiamate asincrone da domini, protocolli o porte differenti. Questa architettura impedisce l'esfiltrazione non autorizzata di dati sensibili garantendo al contempo l'interoperabilità tra servizi web.
- Cos'è REST API: architettura, metodi HTTP e differenze
Una REST API è un'interfaccia di comunicazione software basata sull'architettura Representational State Transfer e sul protocollo HTTP. Permette a sistemi eterogenei di interagire mediante la manipolazione di risorse identificate da indirizzi web univoci. I client eseguono operazioni CRUD utilizzando metodi standard come GET o POST e scambiano payload strutturati, tipicamente in formato JSON.
- Cache web: cos'è e come funziona
La cache web è uno spazio temporaneo sul dispositivo in cui il browser conserva copie di risorse come immagini, font, HTML, CSS e JavaScript. Serve a caricare più velocemente le pagine già visitate e a ridurre il traffico di rete. Non è permanente: i file vengono aggiornati o rimossi secondo regole HTTP e limiti di spazio.
- WebSocket o que é: cos'è e quando usarlo
WebSocket è un protocollo di rete per comunicazione bidirezionale su una connessione TCP persistente. Dopo l'handshake, ciascuna parte può inviare messaggi senza attendere l'altra. È utile per chat, dashboard live, giochi e notifiche, ma non per ogni richiesta HTTP.
- Come funzionano i cookies web: guida tecnica
Un cookie è un piccolo dato che il server invia al browser e che il browser rimanda nelle richieste successive. Serve a ricordare sessioni, preferenze e stato, ma ha limiti di dimensione e impatti su prestazioni e privacy.
Come è stata preparata questa pagina
Prima della stesura, l’argomento è stato studiato sulle fonti qui sotto. La pagina ha poi superato controlli di qualità automatici.