Dagli un RESTO: usa GraphQL per le tue API

Nel mondo dell'architettura API, REST è stato il sovrano regnante per un decennio o più. È probabile che tu usi software creato su un'API REST più volte al giorno sul tuo telefono, computer o qualche altro dispositivo. Forse hai anche lavorato su un'API REST o ne hai scritto uno tu stesso! Nonostante la popolarità di REST, tuttavia, presenta alcuni difetti evidenti.

Cos'è REST?

Nelle API REST, il server definisce un set specifico di risorse che un client può richiedere e queste risorse sono definite da URL univoci. Ad esempio, nell'API per una piattaforma di microblogging generica, l'URL / users / 1 potrebbe indicare il primo utente nel sistema, / users / 1 / posts potrebbe restituire una raccolta di tutti i post scritti dall'utente e / users / 1 / posts / 327 potrebbe restituire un singolo post. REST ha molte sfumature e una specifica ben documentata per il comportamento, ma le risorse basate su URL coprono l'idea di base. Ciò che è in definitiva importante è che il server definisce la struttura dei dati che il client può richiedere.

Cosa c'è di sbagliato in REST?

Immagina di lavorare per la suddetta società Microblogginator ™ generica come sviluppatore di app mobili. Ti viene assegnato il compito di scrivere la vista mobile per il profilo di un utente, che deve mostrare informazioni sull'utente ed elencare i suoi post. Questo non è troppo difficile; basta toccare l'endpoint / users / {id} per ottenere il primo e / users / {id} / posts per ottenere il secondo.

Spedisci la vista mobile e attendi di essere "abbagliato" da tutti i feedback dei clienti e dalle recensioni delle app. La prossima settimana, una volta che tutte le recensioni sono state inserite, riceverai un nuovo requisito. Che Other Microblogger ™ mostra un paio di commenti su ogni post nella loro vista profilo. Perché non lo facciamo anche noi? Fortunatamente, la tua API ha già un endpoint per ottenere i commenti di un post sul blog: / users / {id} / posts / {id} / commenti. Modifichi la vista per raggiungere quell'endpoint per ogni post che mostri sulla pagina del profilo di un utente e il gioco è fatto.

Ma ora la tua app è lenta e questo ci porta a uno dei principali problemi con le API REST:

Troppe richieste HTTP

Ammettiamolo: le applicazioni client raramente rimangono semplici. Il più delle volte, ogni cliente ha una serie abbastanza specifica di requisiti che riflettono i dati di cui hanno bisogno dal tuo sistema. Se fornisci solo un modo assoluto per richiedere dati, otterrai clienti che provano a piantare un piolo romboidale in un foro a forma di diamante.

Nel nostro esempio precedente, la nostra app mobile diventerà sempre più lenta con ogni post che un utente scrive. Se un utente ha venti post elencati sul proprio profilo, stiamo emettendo 22 richieste API. Uno per informazioni sull'utente, uno per il loro elenco di post e quindi venti richieste per ottenere i commenti di ciascun post.

Man mano che aggiungi più componenti all'interfaccia dell'app per dispositivi mobili, questo problema peggiorerà. Con ogni nuovo componente dell'interfaccia utente arriva una nuova chiamata API o una nuova personalizzazione agli endpoint API esistenti. Puoi annidare gli oggetti l'uno nell'altro per evitare ulteriori chiamate API, ma man mano che la tua vista diventa più complessa, inevitabilmente inizierai a nidificare i dati irrilevanti. Finirai con endpoint che non descrivono una singola risorsa ma, invece, una vista di più risorse. Ora la tua API non sembra più così RESTful.

Ancora peggio, sarà necessario supportare tutti i vecchi endpoint purché esistano versioni precedenti di client nel caso in cui si rischi di rompere tali client. Questo porta ad un altro grosso problema con REST:

Le API REST "versioning" sono una seccatura

La struttura delle risposte dalle API REST è importante. I clienti si costruiscono attorno alla consapevolezza che ogni risorsa ha una struttura specifica. Quando Generic Microblogginator ™ ha rilasciato la sua API per la prima volta, ecco come appariva la risposta per ottenere un singolo post:

Dopo che è trascorso un po 'di tempo, decidi che ci sono un paio di cose che vuoi migliorare sulla struttura di un post nell'API. I post stanno per ottenere categorie, quindi dovrai aggiungerli come nuovo campo. Hai anche ricevuto feedback sul fatto che il formato di publishing_at non è molto amichevole. I client JavaScript possono analizzarlo bene, ma preferisci che qualsiasi strumento sia in grado di analizzare facilmente i tuoi timestamp, quindi decidi di cambiarlo in un formato ISO-8601. Quando tutto è detto e fatto, vuoi che la nuova struttura assomigli a questo:

Stai bene! Sfortunatamente, una delle tue modifiche interromperà tutti i tuoi clienti esistenti. Ogni cliente si aspetta che publishing_at sia il formato meno amichevole, quindi è così che proveranno ad analizzarlo. Se desideri aggiornare un campo o rimuovere un campo, devi eseguire la versione dell'API (tramite l'URL o un'intestazione HTTP) e cercare di ottenere l'aggiornamento dei client. È improbabile che tutti i client vengano aggiornati, quindi hai due possibilità:

  1. Stai bene con la rottura delle vecchie versioni dei client (inclusa la tua app)
  2. Supporta le versioni precedenti della tua API fino al giorno in cui la tua azienda decide di annunciare un nuovo capitolo nel loro incredibile viaggio.

La cosa più semplice da fare è semplicemente lasciare solo il tuo vecchio codice, il che significa accumulare sempre più versioni delle tue versioni API in aggiunta a quelle vecchie.

Si avvicina uno sfidante

Inserisci GraphQL, una tecnologia scritta da Facebook. Facebook stava affrontando grossi problemi con la pipeline di dati per le loro applicazioni mobili. Le loro app mobili erano un tempo avvolgenti attorno alle visualizzazioni Web e, con l'aumentare della complessità delle app mobili, hanno iniziato a soffrire di problemi di prestazioni e frequenti arresti anomali. Facebook si è dedicato alla scrittura di applicazioni native e si è trovato a necessitare di una nuova API per recuperare i dati per le loro visualizzazioni native. Hanno valutato REST e altre opzioni ma, dati i problemi come quelli sopra descritti, alla fine hanno colto l'occasione per produrre qualcosa di veramente nuovo.

Che cos'è GraphQL?

GraphQL è, come potrebbe suggerire il nome, un linguaggio di query. È perfetto anche per le API. Ti consente di definire i tuoi dati utilizzando un sistema di tipi a tutti gli effetti, formando uno schema auto-documentante. Fornisce inoltre ai clienti il ​​pieno controllo sui dati richiesti.

Troppe richieste HTTP? Che ne dici di una richiesta HTTP?

Con GraphQL, i client possono ottenere tutti i dati necessari per eseguire il rendering di una vista utilizzando una sola richiesta. Con il nostro esempio di pagina di profilo precedente, un cliente dovrebbe emettere una richiesta per ottenere le informazioni di un utente, una richiesta per ottenere i post di quell'utente e quindi un'altra richiesta per ogni post per ottenere alcuni commenti. Con GraphQL, quel client poteva ottenere tutti i dati sopra con una richiesta:

Boom! Vi sono altri vantaggi a parte il fatto che siamo passati da 22 richieste HTTP a una. Ad esempio, al tuo Utente potrebbero essere associate altre informazioni. Forse esponi il timestamp di quando un utente si è registrato. Forse un altro cliente non si preoccupa delle categorie di un post. Se un client non ha bisogno di eseguire una query per un dato, nemmeno il tuo server. Pertanto, quando un client salva, è possibile salvare anche semplificando le query del database.

Versioning? Basta deprecare!

Come con la maggior parte delle API REST, puoi aggiungere campi ai tipi GraphQL senza paura. Per rimuovere la funzionalità, GraphQL include la deprecazione come funzionalità. Invece di rimuovere completamente un campo e interrompere i client, è possibile dichiarare un campo obsoleto e nasconderlo dagli strumenti con il passare del tempo.

Documentazione: a malapena dovrai preoccuparti

Lasciami essere reale per un secondo qui: posso contare il numero di volte in cui ho usato un'API ben documentata da un lato. Molte volte, le API rimangono prive di documenti o scarsamente documentate. Con GraphQL, il tuo schema è praticamente auto-documentante. Tutto quello che devi fare è fornire i tuoi tipi e campi descrizioni quando necessario, e questo accade nel codice stesso. I clienti possono inviare query GraphQL speciali per introspettersi sullo schema della tua applicazione e conoscere, in una query, tutti i dati che possono richiedere, come si chiama e cosa descrive. Gli sviluppatori possono anche utilizzare strumenti basati su questa introspezione come GraphiQL, che consente ai client di testare le loro query con l'evidenziazione della sintassi in tempo reale e il rilevamento degli errori.

Inizia con GraphQL

Sei abbastanza venduto per provare GraphQL? Ci sono molte risorse per aiutarti a iniziare il tuo viaggio:

  • Controlla il sito Web ufficiale di GraphQL per documentazione ed esempi
  • Gioca con un esempio, l'API GraphQL di Star Wars
  • Le specifiche GraphQL funzionanti se ti piacciono i grintosi

Seguirò anche questo post con un altro, in cui creeremo insieme una piccola API GraphQL, quindi rimanete sintonizzati! Ho avuto l'enorme piacere di lavorare con GraphQL in GitHub e la mia esperienza mi porta a credere con tutto il cuore che è lo strumento API del futuro.