Strumento indispensabile per moltissimi sviluppatori, le Application Programming Interface sono la chiave d’accesso per realizzare architetture scalabili e manutenibili. È il modo con cui ci integriamo abitualmente a applicazioni e piattaforme di vario tipo e con cui permettiamo a terze parti di espandere le funzionalità dei nostri software.
Per molte aziende le api sono diventate un asset aziendale, con un valore tale da poter essere vendute.
Ad esempio, pensa a Google mappe. Integrare all’interno di un sito web la mappa di Google, e geolocalizzare la tua attività, è semplicissimo proprio grazie alle API, attraverso le quali lo sviluppatore può interagire con il programma.
In questo articolo, cercheremo di capire come valorizzare le nostre API e gestirle in maniera efficiente, utilizzando uno strumento aziendale: l’API Gateway.
La bella notizia è che questi concetti non servono solo ai grandi colossi, ma possono essere impiegati da tutte le realtà con ottimi risultati, e portare valore nell’information tecnology.
Cos’è l’API gateway?
L’API gateway è lo strumento che ci permette d’intermediare i servizi ( o microservizi) ed esporli in maniera strutturata verso l’esterno.
Non c’è nulla di fantascientifico in un API-gateway: si tratta di applicazioni web molto sofisticate che agiscono da proxy rispetto alle interrogazioni dei client, monitorando e gestendo il traffico chiamate.
I migliori prodotti sul mercato sono disponibili in versione Saas (software come servizio) o “on premise”, generalmente opensource.
Attraverso l’API-gateway è possibile esporre a terze parti le proprie API sviluppate internamente (magari solo una parte, o un accorpamento di più set diversi) gestendo in maniera efficiente l’autenticazione e monitorandone l’utilizzo.
Lo sviluppatore che desidera utilizzare le API può accedere ad un’area riservata per consultare la documentazione, oltre che a scaricare i contratti in formato Open API swagger o API blueprint.
Ciascuna chiamata è collegata ad un account e quindi possiamo misurare il numero di chiamate fatte, inserire dei limiti per evitare abusi oppure fatturare in base all’utilizzo.
L’API gateway all’interno dell’ IT
L’API gateway è importante anche nel caso in cui le API servono internamente all’IT. Infatti nella maggior parte delle situazioni, anche all’interno dell’IT abbiamo una moltitudine di servizi chiamati “punto-punto”.
Ogni servizio implementa il proprio sistema di logging e l’interazione è generalmente un sistema punto-punto. Ciascun applicativo interagisce con tutti gli altri, rendendo difficile il monitoraggio e la condivisione di documentazione.
Anche in questo contesto l’API gateway è una soluzione utile perché permette:
- di centralizzare il punto di ingresso per le chiamate
- di monitorare le risorse utilizzate
- di gestire in maniera efficiente i log
- di applicare politiche di throttling efficienti
Inoltre, in alcuni scenari fuori standard è un utile paracadute.
Ad esempio possiamo:
- proteggere un servizio che è aperto a tutti
- includere un sistema di tracing su un servizio che ne è sprovvisto
- aggiungere campi fissi su alcune chiamate, astraendo l’utilizzo al chiamante
Quali sono le caratteristiche di un API-gateway?
Sistema di monitoring e analisi
L’API gateway deve essere in grado di registrare ogni singola chiamata, evidenziare ciò che è andato in errore.
Inoltre, le attività monitorate devono essere segmentate per applicativo o per insieme di applicativi. Infine, non necessaria, ma utile, la possibilità di evidenziare tramite grafici l’utilizzo delle risorse.
API Developer Portal
Uno degli obiettivi dell’API gateway è permettere ad ogni utilizzatore di essere indipendente ed autonomo nell’utilizzo delle API.
Questo non significa soltanto riuscire ad effettuare le chiamate ma soprattutto mettere a disposizione la documentazione e gli strumenti per capire come funzionano i servizi.
Deve essere possibile caricare i contratti swagger (Open API) o in altro formato ma soprattutto pubblicare la documentazione e le informazioni utili per gli sviluppatori.
DevOps Oriented
A prescindere dai vincoli tecnologici, il sistema scelto deve essere facile da rilasciare (deployment) e da gestire.
Ormai tutti gli applicativi installabili on-premise supportano Docker, il che li rende molto facili da gestire.
Tuttavia, in base alla propria esperienza e all’infrastruttura che si ha in azienda è importante sincerarsi che il prodotto scelto sia compatibile.
Quota e limiti sulle chiamate
Il sistema API gateway deve essere in grado di impostare limiti sulle chiamate (es. max 1000 richieste per ora per API key).
L’ideale sarebbe avere la possibilità di applicare tali limitazioni per user/ API key o per singolo endpoint.
Inoltre, nel caso in cui si voglia monetizzare o si pensi di volerlo fare in futuro, la possibilità di fatturare le chiamate.
Autenticazione
Questo è il punto più delicato di tutto il processo. La criticità nasce dal requisito che tutti i microservizi hanno necessità di conoscere l’identità del chiamante, così come l’API gateway. I micro servizi, infatti, devono sapere chi chiama in modo da profilare i dati di conseguenza (ad esempio per dare a Mario Rossi l’elenco dei suoi clienti).
Anche l’API gateway ha bisogno di sapere che una determinata API key è collegata ad uno specifico utente per conteggiarli le chiamate e far comparire all’interno del suo profilo utente le statistiche di utilizzo. Per questo occorre appoggiarsi ad un protocollo di autenticazione standard (es. jwt o oauh2) ed un identity server dedicato.
Il passo successivo è far svolgere all’identity server il ruolo di identity broker, che consente di propagare i token di accesso verso gli applicativi, tracciando le chiamate in maniera ottimale.
Questa configurazione non è fuori dagli schemi nella maggior parte dei casi, ma è importante che la soluzione scelta sia compatibile con questa configurazione, anche con un effort lato configurazione.
Mock API
In fase di sviluppo è importante avere una piattaforma che permetta di caricare file swagger (interfacce OpenAPI) o API blueprints per costruire servizi mock (un sistema per simulare le API).
Questo non è un requisito per l’utilizzo a regime, ma aiuta ogni qual volta dobbiamo creare applicativi nuovi. Possiamo, ad esempio, creare un utente “dev” su cui carichiamo i servizi fake. Così sblocchiamo il fornitore che può procedere con lo sviluppo dell’applicativo intanto che i nostri sviluppatori interni realizzano i servizi.
Notifiche ed eventi
Avere un sistema perfettamente funzionante ma isolato non è il massimo. Ci piacerebbe avere la possibilità di ricevere notifiche al verificarsi di determinati eventi.
Il modo in cui ci aspettiamo di avere questa feature è tramite webhook. Questo meccanismo, letteralmente uncino del web, ci permette di sviluppare un nostro applicativo e integrarci con i sistemi pre-esistenti.
Ad esempio possiamo inserire una riga di log sul nostro sistema ELK al verificarsi dell’errore o inserire un ticket su CRM quando un utilizzatore sfora la quota per operazioni commerciali.
Trasformazioni
Non è il motivo per cui va adottato un API-gateway, ma poter alterare richieste e risposte dei servizi per adattarle tra i vari formati è un vantaggio da tenere in considerazioni.
In ogni caso non aspettatevi di poter fare operazioni troppo elaborate, il caso d’uso tipico è inserire parametri costanti, aggiungere header, convertire i payload da json (JavaScript Object Notation) a xml.
Un esempio pratico
Dopo questa veloce panoramica sull’API gateway proviamo a mettere insieme un esempio pratico per valutare un caso d’uso reale.
Gli ingredienti della nostra ricetta:
- API gateway: tyk
- Identity server: redhat keycloak
- App backend: Utilizziamo un cms headless, cockpit! Si tratta di un cms molto semplice che ci permette di mettere in luce diversi casi d’uso.
- docker: utilizzato per far girare in locale tutti gli applicativi
Architettura Api gateway per l’esposizione di microservizi integrati tramite Oaut2
Installazione e configurazione di tyck
Come API-gateway è stato scelto tyk che, oltre a soddisfare tutti i requisiti di cui abbiamo discusso, è facile da configurare oltre ad essere economico. E’ disponibile nella versione saas e onpremise, coprendo quindi la maggior parte dei casi d’uso che ci interessano.
Per l’installazione ho fatto riferimento al progetto di esempio opensource di tyk integrato dentro il nostro file yaml per Docker compose la dichiarazione delle immagini che compongono il gateway (dashboard, gateway, pump).
Per il setup ho utilizzato uno script bash che crea l’utente amministratore e apporta le configurazioni di base per riuscire ad accedere alla dashboard.
Docker-compose up
Accedendo alla url della dashboard http://localhost:5000 viene richiesta la licenza, che possiamo ottenere gratuitamente per fini non commerciali.
inserimento licenza su api gateway Tyck (gratuito per usi non commerciali)
Dopo aver installato la chiave è necessario procedere alla configurazione, per evitare di salire a bordo macchina e lanciare gli script ho utilizzato uno software che utilizza le API e semplifica molto questa fase.
Sh setup.sh
Successivamente è possibile accedere con le credenziali scelte tramite script
Login su api-gateway Tyk
Dashboard dell’api gateway tyk
Installazione e configurazione di keycloak
Per l’installazione di keycloak ho semplicemente utilizzato l’immagine doker rilasciata da redhat.
La configurazione di un client oatuh è banale e può essere effettuata replicando i seguenti passaggi, oppure importando la configurazione presente all’interno del codice sorgente del progetto github.
Keycloak, aggiunta di un nuovo client Oauth2
Keycloak, configurazione dei dati di autenticazione
Keycloak, export configurazione del client Oauth2
Installazione e configurazione di cockpit
Anche per cockpit abbiamo usato un’immagine docker già pronta. L’installazione è molto semplice e con pochi click riusciamo ad aggiungere l’entità “people”.
Cokpit,cms headless: Configurazione entità
API gateway in azione
Il primo passo da fare è mappare gli endpoint che vogliamo esporre.
In questo esempio gli utenti finali utilizzano le API per effettuare le operazioni CRUD sulle entità presenti sul CMS. Per questo creiamo un API set, dichiarando esplicitamente quali metodi sono esposti.
E’ buona prassi segmentare gli endpoint esposti sulla base dell’applicativo, per riuscire ad individuare dove vanno a finire le richieste.
Mappiamo quindi /cockpit/ sul path complesso che viene utilizzato per le attività CRUD
http://cms:8080/api/collections/listCollections
In questo caso vogliamo semplificare il payload di cockpit che è strutturato in maniera troppo complessa per i nostri fini (il vero payload sta dentro un oggetto “data” che è completamente inutile”).
Configuriamo quindi la trasformazione del body della richiesta utilizzando le funzionalità di tyk:
Tyk, api gateway in azione: mappatura campi
Riferimenti
- Il codice sorgente è disponibile su github.
- Tyk.io : Api gateway disponibile in saas o premise.
- Cockpit CMS: Cms Headless in PHP molto facile da installare e configurare.
- Demo Tyk: demo rilasciata da Tyck per illustrare il funzionamento su docker, utilizzata come punto di partenza per questo progetto.
Hai bisogno di sviluppare un’API gateway per il tuo progetto digitale? Ti serve un supporto?