Cos'è GraphQL?
GraphQL è un modo alternativo di comunicare con le API che è altamente adatto per strutture di dati complesse e per costruire interfacce sopra di esse. A differenza del trattamento dei dati come pezzi separati e autonomi, GraphQL mostra come i pezzi di dati si connettono e si relazionano tra loro, rendendo facile richiedere e ricevere informazioni.
Pensa a GraphQL come a un linguaggio di query che ti consente di parlare con l'API come se stessi parlando direttamente al database. Utilizzare GraphQL ti consente di avvicinarti il più possibile al database, permettendoti di scegliere quali dati desideri e come ottenerli, fornendo un enorme vantaggio in termini di prestazioni.
GraphQL è stato creato da Facebook per risolvere il problema della scalabilità con strutture di dati complesse. A seguito della loro adozione di successo, sempre più aziende hanno iniziato a rendersi conto dei vantaggi dell'utilizzo di GraphQL per le loro API.
Differenze chiave rispetto a REST
Le API GraphQL sono più facili da utilizzare di quanto tu possa pensare. Se sei abituato a lavorare con le API REST, ecco le differenze fondamentali da tenere a mente:
| Caratteristica | REST | GraphQL |
|---|---|---|
| Endpoint | Le richieste vengono effettuate a più endpoint per diverse azioni | Tutte le richieste vengono effettuate a un singolo endpoint (ad es., /graphql) |
| Recupero dati | Utilizza metodi GET su endpoint specifici per recuperare dati | Utilizza query per richiedere esattamente i dati necessari, riducendo il sovra-recupero o il sotto-recupero |
| Modifica dati/azioni | Utilizza metodi HTTP come POST, PUT, PATCH o DELETE per modificare o elaborare dati. | Utilizza mutazioni per eseguire operazioni (ad es., creare parti, calcolare costi di sbarco) |
| Formato di risposta | Formati di risposta fissi restituiscono tutti i campi predefiniti, indipendentemente dal fatto che siano necessari | Risposte flessibili consentono di specificare esattamente i campi da includere, riducendo il trasferimento di dati non necessari |
| Connessione dati | Spesso sono necessarie più richieste per recuperare dati correlati | Le query annidate consentono di recuperare dati correlati in una singola richiesta (ad es., dettagli della parte e articoli di spedizione insieme). Gli utenti possono anche costruire flussi di lavoro per gestire più mutazioni all'interno di una singola richiesta GraphQL, riducendo la complessità e migliorando l'efficienza |
Vantaggi di GraphQL
Risposte più rapide
GraphQL fornisce risposte più rapide attraverso un recupero dati preciso, l'uso di un singolo endpoint e capacità migliorate per il batching e la memorizzazione nella cache.
Recupero dati preciso
Una sfida comune con REST è il sovra-recupero o il sotto-recupero dei dati: ottenere troppe informazioni non necessarie o non abbastanza di ciò che è necessario in un colpo solo. GraphQL elimina questo problema consentendo richieste per esattamente ciò di cui hai bisogno—nient'altro, nientemeno. Questa specificità non solo migliora le prestazioni, ma semplifica anche il processo per coloro che interagiscono con l'API, rendendo il sistema più efficiente e user-friendly.
Esempi di come questo sia utile:
- Questo consente agli sviluppatori frontend di recuperare esattamente i dati di cui hanno bisogno per i loro componenti UI, riducendo il numero di viaggi al server e migliorando le prestazioni.
- Immagina di voler ottenere una classificazione del codice HS, cartonizzazione, valutazione della spedizione e un preventivo di landed cost sugli articoli in un checkout. Se sei integrato tramite API GraphQL, puoi effettuare una singola chiamata con i necessari flussi di lavoro per ottenere tutto ciò di cui hai bisogno (e nulla di cui non hai bisogno) in una singola risposta. Al contrario, con le API REST, dovresti prima chiamare il Classify REST API, poi chiamare separatamente il Rating REST API e infine inserire quella classificazione e valutazione della spedizione nella tua terza chiamata al Landed Cost REST API. Tutte queste API REST restituirebbero ogni pezzo di informazione che possono, costringendoti a dover analizzare la risposta per i dati di cui hai bisogno. Questo risparmio in velocità ha un impatto nel restituire un completo landed cost rapidamente, prima che lo shopper se ne vada.
Singolo endpoint
Le API GraphQL tipicamente hanno un singolo endpoint, a differenza delle API REST che spesso hanno più endpoint per diverse risorse e azioni. Questo rende più semplice gestire e comprendere l'API.
Batching e caching
La capacità di GraphQL di raggruppare query e il suo supporto per strategie di caching portano a significativi miglioramenti delle prestazioni. Queste funzionalità riducono il carico su reti e server, traducendosi in interazioni più rapide e affidabili per gli utenti.
Schemi ben definiti
Le API GraphQL si basano su uno schema fortemente tipizzato. Questo schema definisce la struttura dei dati disponibili e le operazioni che possono essere eseguite. Ciò fornisce chiarezza su quali dati sono disponibili e come accedervi, il che può migliorare la produttività degli sviluppatori e ridurre gli errori. Ad esempio, i team frontend possono esplorare il grafo per ottenere esattamente ciò di cui hanno bisogno invece di aspettare un nuovo endpoint REST.
Capacità di migliorare senza interrompere i client esistenti
Aggiungere nuove funzionalità o modificare quelle esistenti in GraphQL non interrompe le integrazioni attuali, grazie alla sua struttura di query flessibile. Questa capacità garantisce che i miglioramenti possano essere apportati senza compromettere la compatibilità con i client esistenti.
Documentazione aggiornata
Grazie alla funzionalità di introspezione di GraphQL, la documentazione viene generata e aggiornata automaticamente con ogni modifica. Questo assicura che tutte le informazioni fornite agli sviluppatori siano attuali, riducendo i problemi di integrazione e i ticket di supporto relativi a documentazione obsoleta—una sfida comunemente affrontata con la documentazione delle API REST.
Consulta la nostra documentazione GraphQL e la nostra documentazione REST per vedere la differenza.
Un'analogia
Immagina di essere in un ristorante con un menu che ti consente di ordinare piatti esattamente come li desideri, rispetto a un altro ristorante dove puoi scegliere solo tra pasti preimpostati. GraphQL è come il primo ristorante:
- Ottieni esattamente ciò che desideri: Con GraphQL, puoi chiedere esattamente i dati di cui hai bisogno, né di più né di meno. Immagina di voler solo il nome e il prezzo di un piatto, non l'intero elenco degli ingredienti. Con le API REST, devi ottenere tutti i dettagli del piatto e ignorare le parti di cui non hai bisogno.
- Componi un piatto personalizzato: Le nostre API GraphQL possono essere facilmente combinate per creare soluzioni più personalizzate, simile a un ristorante in stile buffet dove puoi creare un piatto unico esattamente come lo desideri, utilizzando ingredienti che hanno già. Al contrario, un'API REST è come una panetteria con prodotti preconfezionati in ceste: puoi ordinare solo ciò che è già stato creato e non puoi scegliere di portare a casa solo il pezzo che desideri.
- Meno attesa: Poiché puoi ottenere tutte le informazioni di cui hai bisogno in una singola richiesta, è come chiedere al tuo cameriere di portarti antipasto, piatto principale e dessert tutto in una volta, piuttosto che aspettare tra i corsi. La maggior parte delle API REST richiede di inviare più richieste per ottenere diversi pezzi di informazione.
- Facile modificare gli ordini: Se le esigenze di dati della tua app cambiano, GraphQL rende più facile apportare modifiche. Devi solo cambiare la query per ciò di cui hai bisogno. Con REST, potresti dover aspettare che la cucina (backend) crei un nuovo piatto (endpoint) per il menu, il che richiede più tempo.
GraphQL offre maggiore flessibilità, efficienza e semplicità per recuperare dati rispetto alle API REST, specialmente man mano che le tue esigenze cambiano o crescono.
Come Zonos utilizza GraphQL
Nel corso della modernizzazione della nostra piattaforma negli ultimi anni, Zonos ha scelto di costruire nuove funzionalità utilizzando GraphQL per la nostra API invece di REST. Abbiamo deciso di farlo perché i nostri dati sono complessi e interconnessi, molto simili ai dati che hanno portato Facebook a creare GraphQL. Questa complessità rende difficile costruire API REST scalabili perché i modi in cui gli sviluppatori devono recuperare e utilizzare i dati variano notevolmente tra le implementazioni, e REST non è flessibile.
GraphQL risolve elegantemente questo problema consentendo agli sviluppatori che implementano la nostra API di scegliere esattamente quali dati vogliono e come ottenerli. Questo consente loro di adattarlo ai loro flussi di lavoro senza che Zonos debba fare lavori personalizzati (mentre aspettano) per ogni situazione.
Il risultato combinato dell'uso di GraphQL e delle modernizzazioni nella nostra piattaforma ha reso la nostra API più performante, ha reso più veloce l'integrazione di Zonos nei tuoi sistemi e ha reso possibile per Zonos fornire nuove funzionalità più rapidamente.
Funzionalità migliori
Zonos sviluppa continuamente nuove funzionalità, e GraphQL è il primo (e di solito l'unico) a ricevere questi aggiornamenti. Al contrario, le nostre API REST sono considerate obsolete e non possono accedere a molte delle nostre nuove funzionalità.
Esempi di funzionalità limitate a GraphQL:
- Inclusive pricing
- API delle etichette
- Nuovo Checkout e Hello
- Dimensioni delle scatole nella risposta API
- Reporting del dashboard
- Possibilità di richiedere un preventivo DDP se possibile, ma restituire comunque un preventivo DDU se DDP non è disponibile per quel paese con quel livello di servizio
- Dettaglio delle tasse, imposte e commissioni (informazioni a livello di articolo, commissioni specifiche)—Il dashboard è alimentato da GraphQL e mostra questi dati per tutti i negozi, ma la risposta dell'API REST non include questo livello di dettaglio
- Modalità di test (in arrivo)
Perché GraphQL
Scopri perché raccomandiamo di integrare tramite GraphQL piuttosto che REST.
Presso Zonos, offriamo due principali tipi di API per l'integrazione: GraphQL e REST. Sebbene le API REST siano in circolazione da più tempo e possano essere più familiari a molti, ci siamo spostati su GraphQL per consentire maggiore flessibilità e innovazione più rapida. Sebbene entrambi siano ancora supportati, questa guida spiega perché GraphQL non è solo il futuro delle nostre integrazioni, ma anche il futuro delle integrazioni in generale e uno strumento più potente per soddisfare le tue esigenze oggi.