Guest post: Windows Azure API Management

Questo articolo è stato scritto da Antonio Liccardi , co-founder di DotNetCampania , contributor su GetLatestVersion.it e full-stack developer presso Blexin s.r.l.s .

In questo articolo viene illustrato come semplificare la gestione delle API di un nostro applicativo con l’uso di Windows Azure API Management. Tramite questo servizio abbiamo a disposizione un insieme di tool per rendere più semplice la pubblicazione e la gestione di API per i propri clienti o per l’intera comunità degli sviluppatori.

I compiti che riusciamo a facilitare con Windows Azure API Management sono:

• Documentazione integrata e console per testing;
• Gestione della sicurezza, delle quote e dei limiti;
• Gestione dei formati messi a disposizione (JSON, REST);
• Versioning delle API;
• Monitoraggio sull’uso e sugli errori;
• Analisi sull’uso delle nostre API.

In sostanza, quello che consente di avere a disposizione Windows Azure API Management è un layer aggiuntivo che dà al publisher il pieno controllo delle API arricchendole con un set di funzionalità già pronte (figura 1):

Figura 1 - Windows Azure API Management

Di seguito sarà spiegato prima quali sono i benefici di esporre le API per la propria applicazione, poi verrà illustrato come creare e configurare una prima istanza di Windows Azure API Management. Sempre su questo blog, vedremo poi nei prossimi post, alcuni aspetti avanzati di questo servizio presente in Windows Azure.

L’importanza delle API

Con il termine API si identificano le Application Program Interface, ovvero un set di metodi esposti pubblicamente che consentono agli sviluppatori di interagire direttamente con le applicazioni e i dati in esse contenute. Con questi metodi è possibile:

• Nascondere l’implementazione delle logiche che ci sono dietro un software applicativo;
• Semplificare il compito di uno sviluppatore di terze parti lasciando che richiami le API per il recupero delle informazioni;
• Mettere in comunicazione applicativi diversi, magari creati con tecnologie o scopi differenti;
• Far convergere informazioni provenienti da diverse API in un unico applicativo.

Oggi l’uso delle API è di rilevante importanza soprattutto per le entrate che possono generare. Non a caso, con il termine API economy si evidenzia l’interesse da parti di grandi aziende (non strettamente legate al mondo dell’IT) e social network di esporre le proprie informazioni al fine di generare profitto.

I modi con cui si possono ottenere ricavi dipendono molto dal business model che l’azienda può adottare. Alcuni casi comuni possono essere i seguenti:

• Creare un set di API su cui basare il proprio business, ovvero sul rivendere le informazioni esposte dalle stesse (es.: tramite quote di chiamate, servizi connessi);
• Monetizzazione indiretta, si è partner con altre aziende che tramite l’uso delle API valorizzano l’azienda stessa o il prodotto;
• Semplificare la gestione e il monitoraggio di processi interni ad una azienda mettendo a disposizione delle API di servizio.

Quindi, mettere a disposizione delle API può essere sicuramente favorevole per il proprio business, ma il raggiungimento di questo scopo può richiedere una notevole quantità di energia e risorse. In sostanza occorre una strategia che si basa sul creare un set di API che sia ben organizzato, performante, stabile, e che metta a disposizione tutto il necessario per gli sviluppatori, come la documentazione e il supporto. Visto che il raggiungimento di questo obiettivo non è semplice, Windows Azure ci viene in aiuto con Windows Azure API Management, componente che aiuta a semplificare tutto ciò che ruota intorno alle nostre API, come la gestione, il monitoraggio e il supporto.

Le nostre prime API

Prima di vedere il funzionamento di Windows Azure API Management, occorre una sottoscrizione attiva di Windows Azure (anche trial), l’ultima versione dell’SDK di Azure e un insieme di API da voler esporre. Per il primo punto si può, o accedere al portale di Windows Azure usando l’account legato ad una sottoscrizione attiva, oppure attivare il periodo di prova qui. E’ possibile invece scaricare l’ultima versione dell’SDK da qui.

Per ciò che riguarda un esempio di API da voler esporre, in questo articolo sarà usata l’applicazione BookService realizzata da Mike Wasson per l’articolo “Using Web API 2 with Entity Framework 6”. Questa applicazione illustra un piccolo catalogo di libri e di autori. Il codice è già pronto e disponibile su GitHub a questo indirizzo, ma volendo è possibile seguire tutti i passi per la creazione del progetto da zero nell’articolo sopra citato.

Una volta scaricato il progetto, occorre decomprimere il pacchetto e aprirlo usando Visual Studio. Prima di compilare, bisogna ricordarsi di fare un restore dei pacchetti Nuget presenti nella soluzione.

Una volta compilata la soluzione, si può utilizzare la Package Manager Console di Visual Studio con il comando “Update-Database” per aggiornare il database creato sull’istanza locale, con le tabelle e le informazioni che devono contenere.

Da questo momento in poi si è pronti per la pubblicazione del progetto su una WebApp di Azure: basterà cliccare con il pulsante destro sul nome del progetto e nel menu contestuale che si apre selezionare la voce “Publish” (figura 2):

Figura 2 – Pubblicazione di una applicazione

Nella finestra che compare, cliccare sul pulsante “Microsoft Azure Web Apps” ed effettuare il login a Windows Azure per creare una nuova Web App o per riutilizzarne una già esistente. Quando il sito è pronto, in automatico la finestra Connection (figura 3) contiene le informazioni necessarie per il deploy. Manca solo il database, che si può creare vuoto all’interno del portale di Windows Azure seguendo le indicazioni in questo link e recuperare la stringa di connessione sul portale di Azure per usarla nella casella di testo relativa alla connection string della sezione Settings all’interno di Visual Studio (figura 4). Nel primo deploy, occorre spuntare anche la casellina “Execute Code First Migrations”, necessaria per creare la struttura delle tabelle e il riempimento (seed) delle stesse.

Figura 3 – Le configurazioni per il deploy su una Web App di Azure

Figura 4 – La configurazione per la connessione al DB

E’ tutto pronto per il deploy: basterà cliccare sul pulsante “Publish” e non appena il deploy sarà terminato, si aprirà il browser visualizzando l’applicazione e le relative API pubblicate. E’ possibile verificare le API presenti nell’applicazione pubblicata usando la voce nel menù API; inoltre tramite l’ausilio di un client REST come Fiddler o Postman, si possono eseguire le chiamate seguendo le indicazioni nella Help Page.

Creare una istanza di Windows Azure API Management

Adesso che le API sono pubblicate e pronte per essere usate, si può aggiungere una nuova istanza di Windows Azure API Management. Una volta entrati con la propria sottoscrizione nel pannello di Windows Azure, selezionare l’icona “New” in basso a sinistra ed entrare nella sezione “App Services” . Selezionare poi “API Management” , e subito dopo “Create” (figura 5):

Figura 5 – Creazione di una nuova istanza di API Management

Si aprirà un popup in cui si deve: inserire il nome per il servizio di gestione delle API (casella URL), selezionare la sottoscrizione e scegliere la regione in cui dovrà essere creato (figura 6).

Figura 6 – Impostazioni di base per il servizio (prima schermata)

Nella seconda schermata inserire il nome dell’azienda e l’email dell’amministratore del servizio. Spuntare inoltre la casella “Advanced Settings” per accedere alle impostazioni avanzate (figura 7).

Figura 7 – Impostazioni di base del servizio (seconda schermata)

Nella terza ed ultima schermata occorre impostare il “Pricing Tier” , ovvero il sistema di pricing più adatto per le esigenze del servizio che si sta creando. Ci sono 3 diverse opzioni: Developer, Standard e Premium. In particolare, la prima è ideale per la fase di sviluppo o testing, le altre per la fase di produzione. Nella seguente figura (8) vengono illustrate le differenze:

Figura 8 – Le differenze fra i diversi pricing tier di Windows Azure API Management

Dopo aver impostato come pricing tier “Developer”, terminare il wizard e attendere la creazione del servizio ricordando che la stessa può richiedere fino a 30 minuti.

Il portale di pubblicazione e il portale per gli sviluppatori

All’interno della dashboard del servizio appena creato, è possibile visualizzare i link a 2 portali: il portale di pubblicazione e il portale per gli sviluppatori. Il primo consente di gestire a 360 gradi le API pubblicate. Il secondo invece è un portale personalizzabile e rappresenta il pannello per gli sviluppatori di terze parti che useranno le API (figura 9).

Figura 9 – I due portali disponibili in API Management

Aggiunta di una API a Windows Azure API Management

All’interno del portale di pubblicazione si possono aggiungere e gestire le API precedentemente pubblicate. Infatti, nella sezione dashboard(figura 10), in cui si ha una overview su tutte le API gestite tramite Windows Azure API Management, è possibile cliccare sul pulsante “ADD API” e inserire le informazioni riguardanti le BookService API.

Figura 10 – Aggiunta di una API

I campi da configurare sono i seguenti:

• Web API name: il nome dell’API;
• Web service URL: l’indirizzo originario delle API (comprensivo di eventuali suffissi) che sarà gestito internamente da Windows Azure API Management;
• Web API URL suffix: il suffisso che consente di accedere pubblicamente alle API esposte nell’istanza di Windows Azure API Management;
• Web API URL scheme: lo schema da utilizzare per richiamare le API;
• Products: un product può essere considerato come un contenitore di API a cui si associano delle regole come le quote e i termini d’uso. Nella figura 11, ad esempio, viene selezionato come product “Starter” , che impone un massimo di 5 chiamate per minuto e 100 chiamate per settimana.

Figura 11 – La configurazione di una API

Una volta cliccato su “Save”, si può procedere con la configurazione delle operazioni da esporre tramite questo servizio. E’ importante sapere che non è obbligatorio esporre sempre tutte le nostre API, ma si può scegliere di esporre solo le operazioni da voler mettere a disposizione degli sviluppatori. Pertanto, all’interno della sezione “Operations”, cliccare sul pulsante “ADD OPERATION” al fine di aggiungere il metodo per il recupero di un libro presente nei dati esposti dalle BookService API.

Nella sezione Signature, è possibile definire in che modo l’operazione viene chiamata, la URL, i parametri da passare in input, il nome da visualizzare e il campo descrizione (figura 12). L’aspetto interessante è che informazioni come il campo “Description” consentono di specificare la documentazione per la nostra API che sarà automaticamente riutilizzata nel portale degli sviluppatori.

Figura 12 – Creazione di una nuova operazione

Tra le altre cose che si possono definire ci sono il caching, tutti i dettagli dei parametri e le eventuali risposte previste per l’operazione. In particolare, per le risposte è consentito inserire una descrizione e scegliere la tipologia di rappresentazione per l’output, come ad esempio il formato JSON (figura 13).

Figura 13 – Definizione di una risposta

L’ultimo passo, prima di testare le API, consiste nel creare un utente autorizzato alle chiamate. Nella dashboard del portale di pubblicazione, selezionare la voce Users e all’interno della pagina che si apre, aggiungere un utente selezionando la voce “ADD USER” e inserendo le informazioni necessarie (figura 14).

Figura 14 – Aggiunta di un nuovo utente

Dopo aver salvato le informazioni, occorre associare l’utente alla sottoscrizione Starter andando nel suo dettaglio (basterà cliccare sul nome dell’utente stesso). Da qui, selezionare il pulsante “ADD SUBSCRIPTION” e quindi la sottoscrizione Starter. In questo modo sarà generato un token di accesso che dovrà essere passato come parametro delle nostre API al momento delle chiamate (figura 15).

Figura 15 – Sottoscrizione di un utente ad un product

Testare una API

E’ giunto il momento di testare le nostre API usando il portale degli sviluppatori. Si può aprire quest’ultimo usando il link in alto a destra nella pagina Developer Portal e, loggandosi con l’utente che si è appena creato, si può accedere all’interno della sezione APIS, e di seguito nella sezione “Book Service API”. In questa pagina sono presenti tutte le informazioni relative alla nostra operation ed è anche possibile visualizzare un esempio di codice già pronto all’uso in diversi linguaggi di programmazione (figura 16).

Figura 16 – La descrizione della operation ‘Get Book by Id’

Premendo sul pulsante “Open Console” , si apre una finestra dove è possibile inserire l’id di un libro e selezionando il pulsante “HTTP GET”, viene invocata l’API per ritornare l’informazione ricercata (figura 17).

Figura 17 – La risposta dalla console del portale degli sviluppatori

Inoltre, se si torna nel portale di pubblicazione, è possibile visualizzare una serie di grafici che mostrano il consumo delle API esposte (figura 18).

Figura 18 – Statistiche d’uso delle API

Conclusione

In una era completamente dominata da internet e dal numero sempre più alto di dispositivi interconnessi fra loro, non si può ignorare l’implementazione e l’uso delle API per la condivisione e il recupero dei dati. Purtroppo però, la gestione di un set di API non è sempre semplice, e Windows Azure API Management, di cui in questo post è stata presentata solo una overview, aiuta a semplificare il raggiungimento di questo compito per ottenere il massimo dalle proprie API.