Cos'è GraphQL?
GraphQL è un modo alternativo di parlare con API che è particolarmente adatto per strutture dati complesse e per costruire interfacce su di esse. A differenza del trattamento dei dati come pezzi separati e autonomi, GraphQL mostra come i pezzi di dati si collegano e si relazionano tra loro, semplificando la richiesta e la ricezione di informazioni.
Pensa a GraphQL come a un linguaggio di query che ti consente di parlare con API come se stessi parlando direttamente con il database. L'uso di 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 to solve the problem of scaling with complex data structures. As a result of their successful adoption of it, more and more companies have started to realize the benefits of using GraphQL for their APIs.
Already know REST? GraphQL will feel familiar.
GraphQL APIs are easier to work with than you may think. If you are used to working with REST APIs, here’s how core concepts from REST translate into GraphQL.
| Caratteristica↕ | REST↕ | GraphQL↕ |
|---|---|---|
| Punto finale | Le richieste vengono effettuate a più endpoint per azioni diverse | Tutte le richieste vengono effettuate a un singolo endpoint (ad esempio, /graphql) |
| Recupero dei dati | Utilizza i metodi GET su endpoint specifici per recuperare i dati | Utilizza le query per richiedere esattamente i dati necessari, riducendo il recupero eccessivo o insufficiente |
| Modifica/azioni dei dati | Utilizza i metodi HTTP come POST, PUT, PATCH o DELETE per modificare o elaborare i dati. | Utilizza le mutazioni per eseguire operazioni (ad esempio, creare gruppi, calcolare i costi logistici) |
| Formato della risposta | I formati di risposta fissi restituiscono tutti i campi predefiniti, indipendentemente dal fatto che siano necessari | Le risposte flessibili consentono di specificare esattamente i campi da includere, riducendo il trasferimento di dati non necessario (se questa flessibilità sembra complicata, utilizza semplicemente gli esempi di query già scritti nella nostra documentazione per un'esperienza RESTful) |
| Connessione dati | Spesso sono necessarie più richieste per recuperare i dati correlati | Le query nidificate consentono di recuperare i dati correlati in un'unica richiesta (ad esempio, i dettagli della parte e gli articoli di spedizione insieme). Gli utenti possono anche creare flussi di lavoro per gestire più mutazioni all'interno di una singola richiesta GraphQL, riducendo la complessità e migliorando l'efficienza |
Advantages of GraphQL
Risposte più rapide
GraphQL fornisce risposte più rapide attraverso il recupero preciso dei dati, l'uso di un singolo endpoint e funzionalità migliorate per il batching e la memorizzazione nella cache.
Recupero preciso dei dati
Una sfida comune con REST è il recupero eccessivo o insufficiente dei dati, ovvero l'acquisizione di troppe informazioni non necessarie o di una quantità insufficiente di ciò che è necessario in una volta sola. GraphQL elimina questo problema consentendo richieste esattamente per ciò che è necessario: niente di più, niente di meno. Questa specificità non solo migliora le prestazioni ma semplifica anche il processo per coloro che interagiscono con API, rendendo il sistema più efficiente e facile da usare.
Esempi di come ciò sia utile:
- Ciò consente agli sviluppatori frontend di recuperare esattamente i dati di cui hanno bisogno per i loro componenti UI, riducendo il numero di viaggi di andata e ritorno al server e migliorando le prestazioni.
- Immagina di voler ottenere una classificazione del codice HS, cartonization, valutazione della spedizione e preventivo dei costi di spedizione sugli articoli in fase di pagamento. Se sei integrato tramite GraphQL API puoi effettuare un'unica chiamata con il necessario flussi di lavoro per ottenere tutto ciò di cui hai bisogno (e niente di superfluo) in un'unica risposta. Al contrario, con REST APIs, dovresti prima chiamare il Classify REST API, quindi chiama il Valutazione REST API separatamente in seguito, e infine inserisci la classificazione e la valutazione della spedizione nella tua terza chiamata al Landed Cost REST API. Tutti questi REST API restituirebbero ogni informazione possibile, costringendoti a dover analizzare la risposta per i dati di cui hai bisogno. Questo risparmio di velocità ha un impatto sulla restituzione rapida di un costo logistico completo, prima che l'acquirente se ne vada.
Endpoint singolo
I GraphQL API in genere hanno un singolo endpoint, a differenza dei REST API che spesso hanno più endpoint per diverse risorse e azioni. Ciò semplifica la gestione e la comprensione di API.
Batch e memorizzazione nella cache
La capacità di GraphQL di eseguire query in batch e il suo supporto per le strategie di memorizzazione nella cache portano a miglioramenti significativi delle prestazioni. Queste funzionalità riducono il carico su reti e server, traducendosi in interazioni più veloci e affidabili per gli utenti.
Schemi ben definiti
GraphQL API sono basati 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 grafico per ottenere esattamente ciò di cui hanno bisogno invece di aspettare un nuovo endpoint REST.
Capacità di migliorare senza interrompere i clienti esistenti
L'aggiunta di nuove funzionalità o la modifica di quelle esistenti in GraphQL non interrompe le integrazioni attuali, grazie alla sua struttura di query flessibile. Questa funzionalità garantisce che sia possibile apportare miglioramenti senza interrompere la compatibilità con i client esistenti.
Documentazione aggiornata
Grazie alla funzione di introspezione di GraphQL, la documentazione viene generata e aggiornata automaticamente ad ogni modifica. Ciò garantisce che tutte le informazioni fornite agli sviluppatori siano aggiornate, riducendo i problemi di integrazione e i ticket di supporto relativi alla documentazione obsoleta, una sfida comunemente affrontata con la documentazione REST API.
Rivedi il nostro GraphQL documentazione e il nostro Documentazione REST per vedere la differenza.
Un'analogia
Immagina di essere in un ristorante con un menu che ti permette di ordinare i piatti esattamente come piacciono a te, rispetto ad un altro ristorante dove puoi scegliere solo tra pasti fissi. GraphQL è come il primo ristorante:
- Ottieni esattamente quello che vuoi: Con GraphQL puoi chiedere esattamente i dati di cui hai bisogno, né più né meno. Immagina di volere solo il nome e il prezzo di un piatto, non l'intero elenco degli ingredienti. Con REST APIs, devi ottenere tutti i dettagli del piatto e ignorare le parti che non ti servono.
- Componi un piatto personalizzato: I nostri GraphQL API possono essere facilmente combinati per creare soluzioni più personalizzate, simili a un ristorante a buffet dove puoi creare un piatto unico esattamente come ti serve, utilizzando gli ingredienti che già hai. Al contrario, un REST API è come una panetteria con prodotti già pronti confezionati in cestini: puoi ordinare solo ciò che è già stato creato e non puoi scegliere di portare a casa solo il pezzo che desideri.
- Meno attese: Dato che puoi ottenere tutte le informazioni di cui hai bisogno in un'unica richiesta, è come chiedere al cameriere di portare antipasto, portata principale e dessert tutto in una volta, invece di aspettare tra una portata e l'altra. La maggior parte dei REST API richiedono l'invio di più richieste per ottenere diverse informazioni.
- Ordini facili da modificare: Se i dati della tua app necessitano di modifiche, GraphQL semplifica la modifica. Basta cambiare la query per ciò di cui hai bisogno. Con REST, potresti dover attendere che la cucina (backend) crei un nuovo pasto (endpoint) per il menu, il che richiede più tempo.
GraphQL offre maggiore flessibilità, efficienza e semplicità per il recupero dei dati rispetto ai REST API, soprattutto quando le tue esigenze cambiano o crescono.
Come Zonos utilizza GraphQL
Durante la modernizzazione della nostra piattaforma negli ultimi due anni, Zonos ha scelto di creare nuove funzionalità utilizzando GraphQL per il nostro API invece di REST. Abbiamo deciso di farlo perché i nostri dati sono complessi e interconnessi, proprio come i dati che hanno portato Facebook a creare GraphQL. Questa complessità rende difficile creare REST API 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 perfettamente questo problema consentendo agli sviluppatori che implementano il nostro API di scegliere esattamente quali dati desiderano e come ottenerli. Ciò consente loro di adattarlo ai propri flussi di lavoro senza Zonos dover svolgere un lavoro personalizzato (mentre aspettano) per ogni situazione.
Il risultato combinato dell'utilizzo di GraphQL e delle modernizzazioni della nostra piattaforma ha reso il nostro API più performante, ha reso più rapida l'integrazione di Zonos nei tuoi sistemi e ha reso possibile per Zonos fornire nuove funzionalità più rapidamente.
Funzionalità migliorate
Zonos sviluppa continuamente nuove funzionalità e GraphQL è il primo (e solitamente l'unico) a ricevere questi aggiornamenti. Al contrario, i nostri REST API sono considerati a fine vita e non possono accedere a molte delle nostre nuove funzionalità.
Esempi di funzionalità limitate a GraphQL:
- Inclusive pricing
- Etichette API
- Nuovi Checkout e Hello
- Dimensioni della scatola nella risposta API
- Dashboard segnalazione
- Possibilità di richiedere un preventivo DDP se possibile, ma di restituire comunque un preventivo DDU se DDP non è disponibile per quel Paese con quel livello di servizio
- Suddivisione dettagliata di dazi, tasse e commissioni (informazioni a livello di articolo, tariffe specifiche): Dashboard è basato su GraphQL e mostra questi dati per tutti i negozi, ma la risposta REST API non include questo livello di dettaglio
- Modalità test (disponibile a breve)
Perché GraphQL
Scopri perché consigliamo l'integrazione tramite GraphQL su REST.
A Zonos offriamo due tipi principali di API per l'integrazione: GraphQL e REST. Sebbene i REST API siano in circolazione da più tempo e potrebbero essere più familiari a molti, siamo passati a GraphQL per consentire una maggiore flessibilità e un'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 odierne.