GraphQL è una tecnologia sempre più popolare tra gli sviluppatori perché consente di creare API intuitive, flessibili da usare e facilmente estensibili. Non a caso il numero di API GraphQL accessibili pubblicamente come, ad esempio, quelle fornite da GitHub, Yelp, Netflix o Shopify, continua a crescere. Le sue origini risalgono al 2012: creato da Facebook per descrivere le capacità e i requisiti dei modelli di dati per le applicazioni client-server in sostituzione alle API REST, lo sviluppo di questo standard aperto è iniziato nel 2015 e oggi è un punto fermo dei microservizi.
GraphQL: che cos’è e come funziona
GraphQL è sia un linguaggio di query per le API (Application Programming Interface) che un motore di esecuzione lato server. Nello specifico, la tipologia di query è un oggetto speciale che definisce tutti i punti di ingresso di primo livello (data layer) per le query eseguite dai client al server. Linguaggio di query statico con tipizzazione forte, GrapQL consente ai client di specificare in modo dichiarativo i propri requisiti di dati ottimizzando il data caching.
I client specificano la forma dei dati di cui hanno bisogno e il server risponde con la stessa identica forma della risposta. Grazie alla natura flessibile di GraphQL, è possibile apportare modifiche lato client senza alcun lavoro aggiuntivo sul server. Poiché i clienti possono specificare i loro esatti requisiti di dati, nessun ingegnere di back-end deve apportare modifiche quando la progettazione e le esigenze di dati sul front-end cambiano.
GraphQL, infatti, fornisce una descrizione completa e comprensibile dei dati contenuti nell’API, offrendo ai client la possibilità di chiedere esattamente ciò di cui hanno bisogno e nient’altro. Le app che utilizzano GraphQL sono veloci e stabili perché controllano i dati che ottengono, non il server. Questo semplifica l’evoluzione delle API nel tempo, abilitando potenti strumenti di sviluppo.
Neo4j GraphQL e i plus di una libreria JavaScript opensource
Neo4j è un database grafico nativo open-source, NoSQL, che fornisce un backend transazionale conforme ad ACID e sviluppato utilizzando la tecnologia Java. È altamente scalabile e privo di schemi (NoSQL). La libreria Neo4j GraphQL è una libreria JavaScript open source altamente flessibile, low-code che consente lo sviluppo rapido di API per applicazioni mobili e multipiattaforma sfruttando la potenza dei dati connessi.
Con Neo4j come database grafico, la libreria GraphQL semplifica la gestione dei dati applicativi che vengono trattati come un grafico in modo nativo dal front-end fino all’archiviazione, evitando il lavoro sullo schema duplicato e garantendo un’integrazione perfetta tra sviluppatori front-end e back-end. Scritto in TypeScript, il paradigma schema-first della libreria consente agli sviluppatori di concentrarsi sui dati dell’applicazione di cui hanno bisogno, occupandosi allo stesso tempo del lavoro pesante coinvolto nella creazione dell’API.
API REST vs GraphQL: lo sviluppi delle API di nuova generazione
Negli ultimi dieci anni, REST (Representational State Transfer) è diventato lo standard per la progettazione di API Web. REST è un modello semplice e flessibile per la condivisione di risorse tra i servizi Web. Tuttavia, questa tecnica presenta alcuni aspetti negativi che causano seri problemi di prestazioni nei dispositivi mobili con larghezza di banda ridotta. A fronte di alcuni indubbi vantaggi come, ad esempio, il server senza stato e l’accesso strutturato alle risorse, le API REST risultano troppo rigide per stare al passo con i requisiti in rapida evoluzione dei client e della programmazione.
Uno dei problemi più comuni con REST, ad esempio, è l’overfetching, il che sta a significare che un client scarica più informazioni di quelle effettivamente richieste nell’app. Questo accade perché l’unico modo in cui un client può scaricare i dati è colpire gli endpoint che restituiscono strutture di dati fisse, il che rende difficile progettare l’API in modo che sia in grado di fornire ai clienti le loro esatte esigenze di dati.
Oltre ad accedere alle proprietà di una risorsa, le query GraphQL, seguono agevolmente i riferimenti che sussistono tra le varie risorse. A differenza delle API REST, che richiedono il caricamento da più URL, le API GraphQL ottengono tutti i dati necessari allo sviluppo di una app in un’unica richiesta: GraphQL invia una singola query al server GraphQL che include i requisiti di dati concreti e, a sua volta, il server risponde con un oggetto JSON in cui questi requisiti sono soddisfatti.
Perché le API realizzate con GraphQL sono più veloci
GraphQL consente ai client di specificare in modo dichiarativo quali dati desiderano recuperare, non come dovrebbero essere recuperati: basta effettuare una sola richiesta HTTP e la risposta è completamente personalizzabile. GraphQL è anche sicuro dai tipi, il che significa che il client API che si sta utilizzando può verificare che i dati richiesti siano corretti.
GraphQL non è legato a nessun database o motore di archiviazione specifico in quanto è supportato dal codice e dai dati esistenti. Consentendo ai client di recuperare solo i dati desiderati e di farlo in un’unica richiesta http, la API realizzata richiede minore larghezza di banda (recuperando solo i dati necessari) e meno roundtrip (non dovendo effettuare una richiesta separata per risorsa correlata). Questa velocità intrinseca fa si che le app che utilizzano GraphQL siano veloci anche su connessioni di rete mobile lente.
I vantaggi di usare GraphQL
GraphQL aiuta a creare API flessibili, che si adattano alle mutevoli e crescenti esigenze di servizio, garantendo uniformità tra le applicazioni. Quando le applicazioni devono essere modificate per aggiungere funzionalità o rimuovere funzionalità non utilizzate, i campi corrispondenti nella query possono essere modificati ed eseguiti semplicemente, riducendo drasticamente sia il lavoro di programmazione che il tempo di interruzione.
L’obiettivo di GraphQL è fornire agli sviluppatori una visione completa dei dati archiviati all’interno di un’API, con la possibilità di ricevere solo dati rilevanti e di usufruire di un’architettura che renda le API più facili da scalare e da adattare nel tempo. Chi si occupa di sviluppare le interfacce utente (UI), ad esempio, ama la semplicità di lavorare con un’API concettuale, soprattutto nel caso di un dominio di grandi dimensioni. Gli sviluppatori che lavorano sul back-end adorano il disaccoppiamento e la resilienza offerti dal livello API. Ma con l’aumentare dei microservizi e del numero di sviluppatori, lo sviluppo del livello di aggregazione API può diventare estremamente complesso.
Microservizi e API management
La specializzazione nella gestione del dato ha portato a una architettura più dinamica che si è progressivamente liberata dalle complessità della manutenzione legata al concetto classico di server e sistema operativo. Rispetto a un approccio monolitico tradizionale, dunque, un’architettura basata sui microservizi consente di suddividere una app nelle sue funzioni di base.
Questo consente allo sviluppatore di poter compilare e implementare ogni funzione in modo indipendente. Il vantaggio di questo tipo di programmazione è che i singoli servizi possono funzionare o non funzionare senza che gli altri servizi ne siano impattati. L’architettura a microservizi prevede, infatti, che il codice sia strutturato in modo da garantire obbligatoriamente una serie di vantaggi rispetto ai tradizionali pattern di sviluppo.
Perché GitHub ha introdotto le API GraphQL
Le API REST di GitHub erano responsabili della gestione del 60% delle richieste inviate ai loro server. Queste API non erano scalabili il che ha iniziato a incidere sulle prestazioni man mano che le applicazioni diventavano più complesse. Ecco perché, già nel settembre del 2016, GitHub aveva ufficialmente dato l’annuncio che avrebbe usato GraphQL nelle sue API pubbliche. Come si poteva leggere nel comunicato “Le nostre risposte erano gonfie e piene di tutti i tipi di suggerimenti *_url nelle risposte JSON per aiutare le persone a continuare a navigare attraverso l’API e ottenere ciò di cui avevano bisogno. Nonostante tutte le informazioni che abbiamo fornito, per gli integratori la nostra API REST non era molto flessibile. A volte erano necessarie due o tre chiamate separate per assemblare una vista completa di una risorsa. Sembrava che le nostre risposte inviassero contemporaneamente troppi dati e non includessero i dati di cui gli utenti avevano bisogno. Con e API REST avevamo anche riscontrato problemi durante la raccolta di meta informazioni sugli endpoint: volevamo raccogliere alcune meta-informazioni sui nostri endpoint (ad esempio, identificare gli ambiti OAuth richiesti per ciascun endpoint), essere più intelligenti su come venivano impaginate le nostre risorse e avere garanzie di sicurezza del tipo per i parametri forniti dall’utente, per produrre una valida documentazione dal nostro codice. Con GraphQL, GitHub siamo in grado di progettare i nostri server per inviare solo i campi richiesti dal client. Ciò aiuta a migliorare le prestazioni dei client di app mobili in cui sono richiesti carichi utili più piccoli”.
GraphQL nelle API di Yelp
Yelp fornisce strumenti utili per tutti gli sviluppatori. In questo momento GraphQL è ancora nel periodo beta, il che significa che la società non può promettere che sia completamente stabile o che parte dell’implementazione esistente non cambierà.
Come avvertono sulla pagina aziendale dedicata. “Se non ti senti a tuo agio nel trovare un bug o due e apportare modifiche alla tua app per stare al passo con noi, l’API normale sarà più adatta. GraphQL rimarrà in versione beta per un po’ mentre risolviamo i bug e appianiamo le cose. Al momento non abbiamo una sequenza temporale per quando GraphQL sarà considerato stabile in produzione. Per ora, limiteremo GraphQL a 10.000 query al giorno mentre lo andremo a potenziare progressivamente. Se utilizzi più query in una singola richiesta, conteremo ogni singola query chiamata, quindi 3 utilizzi delle query aziendali in una singola richiesta conteranno 3 sul totale. Per gli sviluppatori, sia GraphQL che l’API normale utilizzano la stessa autenticazione, per cui potranno essere intercambiabili all’interno della app”.
GraphQL e il modello federato di Netflix
Netflix è noto per la sua architettura di microservizi poco accoppiata e altamente scalabile. I servizi indipendenti consentono un’evolutiva a ritmi diversi e una scalabilità più agile e indipendente, aggiungendo però complessità in tutti quei casi d’uso che si estendono su più servizi. Anziché esporre centinaia di microservizi agli sviluppatori dell’interfaccia utente, Netflix offre un livello di aggregazione API unificato sull’edge.
Il team di sviluppo ha realizzato una piattaforma GraphQL federata per potenziare il livello API, risolvendo molte delle sfide di coerenza e velocità della programmazione, con compromessi minimi in termini di flessibilità e operabilità. Il team di sviluppo ha iniziato a creare un’API grafica chiamata Studio API con l’obiettivo di fornire un’astrazione unificata su dati e relazioni. L’API di Studio ha utilizzato GraphQL come tecnologia API sottostante e ha creato una leva significativa per l’accesso ai dati condivisi di base.
I consumatori dell’API di Studio hanno potuto così esplorare il modello grafico per creare nuove funzionalità più rapidamente. Grazie al nuovo framework, i team di sviluppo hanno osservato un minor numero di casi di incoerenza dei dati tra diverse applicazioni dell’interfaccia utente, poiché ogni campo in GraphQL si risolve in un singolo pezzo di codice di recupero dei dati.
A fronte del successo della soluzione, i team di prodotto che hanno apprezzato la riutilizzabilità e un accesso ai dati facile e coerente. Con l’aumento del numero di consumatori di Netflix e della quantità di dati nel grafico sono emersi nuovi colli di bottiglia. Mentre i programmatori stavano cercando una soluzione, nel 2019 Apollo ha rilasciato la specifica della federazione GraphQL che ha permesso di coniugare i vantaggi di uno schema unificato con proprietà e un sistema di implementazione distribuito. Il successo del nuovo framework di sviluppo ha portato Netflix a collaborare con Apollo sul futuro della GraphQL Federation.
Che cos’è il modello federato delle API
Dal primo livello monolitico, che esponeva tutti i tipi di funzionalità su un insieme di dati in modo incoerente tra i servizi, al secondo livello tramite accesso diretto o al terzo livello relativo all’aggregazione a livello di gateway, il gateway federato è l’ultima frontiera dello sviluppo delle API. Il modello federativo mette a sistema principi di progettazione, strumenti e infrastruttura, consentendo di esporre un insieme di servizi e flussi di eventi all’interno di un particolare contesto delimitato come API unificata e coerente per i clienti esterni, consentendo al contempo singoli servizi all’interno il contesto limitato per evolversi e cambiare senza ulteriori restrizioni.
La nozione di contesto limitato e di strumenti come la mappatura del contesto ci aiutano a pensare in modo efficace all’intero panorama API di un’organizzazione. Rimane ancora da capire in che modo la federazione API influisca sulla progettazione di ciascuno dei servizi implementati all’interno di un contesto.
Le novità introdotte dal GraphQL Federation Model
Dal punto di vista della federazione API, la sfida progettuale chiave è decidere la giusta modularità dei singoli servizi. Poiché la federazione API introduce un meccanismo per comporre dati e funzionalità in modo efficace, i team API possono concentrarsi su caratteristiche API più granulari e modulari che possono essere implementate e versionate in modo indipendente, delegando la generazione finale dell’interfaccia per l’intero contesto limitato al livello della federazione.
La progettazione, basata sulle funzionalità, propone un approccio dal basso verso l’alto, in cui le interfacce sono scomposte in funzionalità modulari che possono essere rilasciate in modo indipendente e con un contratto standard tra servizi e team.
Come e perché è difficile controllare l’evoluzione delle API
In conclusione, gestire il cambiamento nei sistemi software non è mai facile, ma è particolarmente difficile gestire il cambiamento nei sistemi distribuiti debolmente accoppiati, come nel caso delle API. Nei sistemi distribuiti debolmente accoppiati non solo i componenti software stessi sono distribuiti, ma anche le responsabilità dei diversi componenti sono distribuite su diverse organizzazioni, aziende e persone.
Il fornitore dell’API non solo ha uno scarso controllo sulle implementazioni client del consumatore che utilizzano l’API ma potrebbe non conoscere nemmeno tutte le applicazioni del consumatore che chiamano l’API. Ciò significa che un numero imprecisato di componenti software non identificati potrebbe fare affidamento sull’API: ma basta una piccola modifica nell’API per interrompere alcuni dei client che la utilizzano.
Se l’interfaccia dell’API cambia comunque, è impossibile per il provider dell’API modificare tutte le app che utilizzano l’API ed è altrettanto impraticabile costringere tutti i consumatori ad adattare o aggiornare le proprie app. I consumatori di API in genere non sono disposti e non sono interessati a gestire le API che cambiano frequentemente e abbandoneranno rapidamente le API che li costringono a riscrivere le loro app.
La semplice regola per l’evoluzione dell’API
La semplice regola per l’evoluzione dell’API è che il comportamento osservabile esternamente di un’API (dal punto di vista dei client) non può essere modificato, una volta che l’API è stata pubblicata. Già una piccola modifica dell’API potrebbe interrompere alcuni dei client che utilizzano l’API. È impossibile aggiornare tutti i consumatori o, quantomeno, è irrealistico dal momento che sono sotto il controllo di diversi proprietari. Pertanto, la longevità e la stabilità sono aspetti importanti delle API pubblicate.
Come creare un API utilizzando GraphQL
Per creare API utilizzando GraphQL, sono necessari:
- un server GraphQL che ospita l’API
- un client che si connette a un endpoint
Come sono organizzate le API GraphQL
Più nel dettaglio, le API GraphQL sono organizzate per tipi e campi che vengono definiti in base ai dati, non agli endpoint. Nello specifico i campi, nell’insieme di selezione di livello superiore di un’operazione, spesso rappresentano alcune informazioni accessibili a livello globale all’applicazione e al relativo visualizzatore corrente. GraphQL utilizza un sistema di tipi avanzati per definire le capacità di un’API. Tutti i tipi esposti in un’API vengono annotati in uno schema utilizzando GraphQL Schema Definition Language (SDL), che funge da contratto tra il client e il server per definire come un client può accedere ai dati.
Una volta definito lo schema, i team che lavorano su front-end e sul back-end possono svolgere il proprio lavoro senza ulteriori comunicazioni poiché entrambi sono consapevoli della struttura definita dei dati inviati sulla rete. I team di front-end possono facilmente testare le loro applicazioni. Una volta che il server è pronto, è possibile girare l’interruttore affinché le app client carichino i dati dall’API effettiva. Inoltre, è possibile aggiungere nuovi campi e tipi alla API GraphQL che si sta sviluppando, senza influire sulle query esistenti. I campi obsoleti possono essere deprecati e nascosti agli strumenti. Utilizzando un’unica versione in evoluzione, le API GraphQL offrono alle app l’accesso continuo a nuove funzionalità e incoraggiano un codice server più pulito e manutenibile.
I tre asset di GraphQL
Le API GraphQL sono composte da tre elementi:
- Schema: è il sistema di tipi utilizzato per definire un’API all’interno di un’implementazione del server. Tutte le capacità e le funzionalità sono definite all’interno dello schema.
- Query: la richiesta, o istruzione, per l’output effettuata. Le nuove query vengono dichiarate con una parola chiave e possono supportare campi, array e argomenti nidificati.
- Resolver: indica a GraphQL come e dove è possibile trovare i dati in relazione ai campi indicati. Senza questo, il server GraphQL non saprebbe come gestire una query.
Le query GraphQL, infatti, restituiscono sempre risultati prevedibili, utilizzando i tipi per garantire che le app richiedano solo ciò che è possibile e forniscano errori chiari e utili. Le app possono utilizzare i tipi per evitare di scrivere codice di analisi manuale. Senza uscire dall’editor, lo sviluppatore può scoprire esattamente quali dati può richiedere all’API, evidenziando potenziali problemi prima di inviare una query, sfruttando così la migliore intelligenza del codice.
Dopo che un servizio GraphQL è in esecuzione (in genere in corrispondenza di un URL su un servizio Web), può ricevere query GraphQL da convalidare ed eseguire. Il servizio prima controlla una query per assicurarsi che faccia riferimento solo ai tipi e ai campi definiti, poi esegue le funzioni fornite per produrre un risultato.
