Web API in formato OpenAPI

Documentazione storica, non aggiornata.

Nei paragrafi precedenti abbiamo visto come consumare o esporre Web API REST scrivendo manualmente il codice di gestione delle chiamate. Ora vedremo come automatizzare questo processo tramite lo standard OpenAPI.

La specifica OpenAPI (OAS) definisce un’interfaccia standard, indipendente dal linguaggio, per le Web API REST che consente sia agli esseri umani che ai computer di scoprire e comprendere le funzionalità del servizio senza accedere al codice sorgente o alla sua documentazione. Definendo un linguaggio comune, le Web API OpenAPI possono essere consumate da qualsiasi client che adotti questo standard.

Instant Developer Cloud implementa lo standard OpenAPI in maniera completa, infatti:

Contiene un framework di generazione automatica di Web API esposte in formato OpenAPI a partire dai documenti contenuti nell’applicazione.
Permette di importare una Web API OpenAPI esistente generando automaticamente le classi di documento corrispondenti e generando anche tutti i metodi esposti dalla Web API.

Esposizione di documenti via Web API OpenAPI

Esporre un documento di un progetto via OpenAPI è molto semplice: è sufficiente impostare la proprietà Abilita Web API a design time nella classe documento. I possibili valori sono:

Metodi: sarà possibile solo chiamare i metodi del documento specificatamente abilitati per l’utilizzo tramite Web API.
Metodi+Lettura: sarà possibile effettuare delle query di lettura dati estraendo documenti e collection, oltre che chiamare i metodi specificatamente abilitati per l’utilizzo tramite Web API.
Metodi+Lettura+Scrittura: sarà possibile effettuare delle query di lettura dati, inserire, modificare e cancellare i documenti, oltre che chiamare i metodi specificatamente abilitati per l’utilizzo tramite Web API.

L’esposizione delle Web API nella classe documento a design time definisce che la stessa operi in modalità sia OpenAPI che OData.

Per le Web API descritte in modalità OpenAPI l’importazione in un client avviene mediante lo specificationUrl che si ottiene dalla pagina di Swagger della Web API esposta.

Swagger è un’interfaccia utente che permette agli sviluppatori e ai tester di interagire con un’API direttamente nel browser. Con Swagger è possibile esplorare le diverse operazioni esposte dall’API, vedere la documentazione e persino fare chiamate di prova direttamente da un browser. In passato, Swagger era il nome sia della specifica che degli strumenti. Ora, la specifica è chiamata OpenAPI, mentre Swagger si riferisce agli strumenti che supportano questa specifica. La pagina di Swagger è visualizzabile da un browser specificando l’indirizzo dell’applicazione, cioè la URL dell’installazione, seguita da api-docs. Ad esempio:

https://examples.instantdevelopercloud.com/datamapdesignpatterns/api-docs

Lo specificationUrl è l’indirizzo del file json che descrive le Web API ed è quello che va utilizzato per importarle. Ad esempio:

https://examples.instantdevelopercloud.com/datamapdesignpatterns/openapi.json

La pagina di Swagger della Web API OpenAPI è un’interfaccia utente che genera automaticamente documentazione leggibile e interattiva delle API basata sulla specifica OpenAPI (usufruibile da un client OpenAPI ma anche da una persona). Questa interfaccia consente di visualizzare, esplorare e testare gli endpoint direttamente nel browser.

L’immagine sottostante è un esempio di interfaccia di Swagger per una Web API in formato OpenAPI:

In questa pagina, la prima informazione che è possibile vedere è l’indirizzo del file json che descrive la OpenAPI. Dalla pagina Swagger delle Web API OpenAPI è possibile testare le funzioni di GET, POST, PATCH e DELETE e tutti i metodi custom esposti direttamente dal browser.

Autenticazione Web API OpenAPI

Abilitando le Web API per una classe di documento, esse saranno subito attive al momento dell’installazione dell’applicazione su un server. È quindi necessario aggiungere un livello di autenticazione per controllare che il chiamante abbia il permesso di accedere ai documenti esposti. A tal fine è possibile implementare l’evento onCommand, che viene notificato prima di procedere con l’elaborazione della richiesta, come mostrato nell’esempio seguente:

App.Session.prototype.onCommand = function (request)
{
  if (app.isWebApiRequest()) {
    let token = "Basic " + App.Utils.toBase64(app, "alladin:opensesame");
    if (request.headers.authorization !== token) {
      app.sendResponse(401, { error: {
        message: "Authorization token is not valid"}
      }, {contentType: "application/json"});
      return;
    }
  } 
};

Per disabilitare la gestione automatica della richiesta Web API è sufficiente chiamare il metodo app.sendResponse. Nei casi reali si consiglia di verificare il token di autenticazione in base ad una lista di token validi, che possono essere memorizzati anche su una tabella del database.

Testare la Web API OpenAPI esposta

Nel caso di Web API OpenAPI non è possibile eseguire il test tramite l’anteprima nell’IDE, ma è invece necessario installare l’applicazione in un server di test o di produzione. Per sapere come si esegue l’installazione di un’applicazione in un server di test o di produzione occorre consultare il manuale I server di produzione. Dopo aver pubblicato la Web API sarà possibile testarla o importarla da uno specifico client OpenAPI.

Particolarità dell’implementazione OpenAPI

Il file di specifica dei documenti esposti come WebAPI (openapi.json) viene generato automaticamente dal framework al momento della pubblicazione in un server di produzione. Questo comporta che non è possibile aggiungere manualmente ad esso le specifiche che definiscono il tipo di autenticazione implementata nell’applicazione.

Per questo motivo, il file di specifica include sempre nella sezione Authorize il metodo di autenticazione apiKeyAuth.

Se invece nell’applicazione è stato implementato un metodo di autenticazione diverso da apiKeyAuth, il client dovrà comunque passare nell’header Authorization il nome ed il valore del vero metodo di autenticazione. Ad esempio se l’autenticazione utilizzata dalla Web API esposta è quella basic, l’header Authorization dovrà essere impostato alla costante “Basic “ seguita dalla stringa nome utente + “:” + password in formato base64.

Importazione e utilizzo di Web API OpenAPI

In questo paragrafo vediamo come utilizzare una Web API esistente in formato OpenAPI in un progetto.

Passo 1 – importazione

Per importare una Web API di formato OpenAPI è sufficiente utilizzare il comando di importazione nella dashboard del progetto nell’IDE. A questo punto occorre inserire la URL del file di configurazione della Web API, che può essere in formato JSON o YAML. Il server che contiene il file deve servirlo tramite https e deve accettare l’header Accept con valori “application/yaml” e “application/json”.

Se la Web API è stata creata con Instant Developer Cloud, la URL del file di configurazione può essere recuperata dalla pagina che descrive le Web API, come mostrato dall’immagine seguente (vedi riquadro rosso).

Per ogni altro servizio cloud pubblico, i file di descrizione possono essere trovati con una normale ricerca sul web. Se il file di descrizione non è disponibile, può essere creato manualmente tramite un editor apposito oppure anche tramite sistemi di intelligenza artificiale.

La funzione di importazione crea automaticamente nel progetto una nuova libreria che contiene i documenti relativi alle entità esposte dalla Web API. Nella libreria relativa all’API viene creata anche una classe denominata MainClass che contiene i metodi esposti dalla Web API OpenAPI.

Nell’immagine sottostante vediamo un esempio della classe MainClass importata con alcuni metodi:

All’interno di MainClass vengono create tante cartelle quante sono le entità importate, con all’interno i relativi metodi. Nell’immagine precedente vediamo la cartella Category che contiene i metodi getCategory1 e getCategory che si differenziano principalmente per i parametri di ricerca.

È possibile rinominare i metodi come si preferisce; ad esempio per quello che opera per chiave primaria si potrebbe utilizzare il nome getCategoryByKey, e usare getCategory per quello generico. È possibile cambiare anche il nome alla MainClass.

Passo 2 – configurazione endpoint

L’endpoint della Web API importata viene memorizzato all’atto dell’importazione e può essere modificato a design time tramite la proprietà specificationUrl della classe MainClass.

È possibile modificare il valore di specificationUrl anche a runtime, indicandolo nel costruttore dell’istanza di MainClass come specificato di seguito:

let myOpenAPI = new App.ServiceForDatamapDesignPatterns.MainClass(app, {
    specificationUrl : "https://prod3-pro-gamma.instantdevelopercloud.com/               
    				datamapdesignpatterns/openapi.json"
});

È possibile utilizzare la proprietà specificationUrl per impostare l’indirizzo di connessione invece di passarlo come parametro del costruttore.

Passo 3 – autenticazione

Per impostare l’autenticazione alla Web API occorre verificare quale metodo o quali metodi, se più di uno, è possibile utilizzare per autenticarsi. L’autenticazione la troviamo nella pagina che descrive la Web API cliccando sul pulsante Authorize, come rappresentato nell’immagine sottostante (vedi riquadro rosso).

Nel popup che si apre si possono recuperare le informazioni necessarie ad eseguire l’autenticazione. Nel riquadro rosso dell’immagine seguente troviamo il metodo da utilizzare indicato dentro le parentesi tonde (al numero 2) e l’eventuale name da passare nei parametri (al numero 1).

Nel caso illustrato nell’immagine, che indica di utilizzare la modalità apiKey, dovremo utilizzare il metodo setApiKeyAuthentication, uno dei metodi dell’istanza della classe MainClass. Dopo aver creato l’istanza di MainClass, si potranno impostare i valori di autenticazione chiamando i relativi metodi, ad esempio:

myOpenAPI.setApiKeyAuthentication("apiKeyAuth", "valore-key");

Il primo parametro è quindi impostato al valore apiKeyAuth come indicato al numero 1 nell’immagine precedente.

Le possibili modalità di autenticazione e il relativo metodo da utilizzare sono:

Basic – setBasicAuthentication
apiKey – setApiKeyAuthentication
Bearer – setBearerAuthentication
OAuth2 – setOauth2Authentication
openIdConnect – setOauth2Authentication

Passo 4 – utilizzo

A questo punto è possibile chiamare l’API utilizzando i relativi metodi dell’istanza di MainClass. Il valori di ritorno delle chiamate vengono già convertiti in documenti e collection se sono specificati nella descrizione dell’API.

Tali documenti sono da considerare come semplici strutture dati e non prevedono i cicli di caricamento e salvataggio tipici dei documenti. Sia il caricamento che il salvataggio dovranno quindi essere effettuati tramite i metodi dell’istanza di MainClass.

Utilizzando le DataMap è possibile mostrare in una videata i dati dei documenti restituiti dall’API.

Vediamo un caso di utilizzo pratico caricando una lista di foto dalle Web API di unsplash.com.

Per prima cosa occorre importare la Web API utilizzando il file che la descrive che troviamo qui.

A questo punto abbiamo a disposizione il metodo getSearchPhotos della MainClass importata e possiamo utilizzarlo come nell’esempio seguente:

let m = new App.UnsplashPhotoSearchAPI.MainClass(app);
m.specificationUrl = "https://prod3-pro-gamma.instantdevelopercloud.com/" 
  + "fiori/files/uploaded/openapi.yml";
m.setApiKeyAuthentication("apiKeyAuth", "indicare il proprio Client ID");
let b = yield m.getSearchPhotos({query : "sea"});

Come valore di ritorno dalla Web API otteniamo una collection di documenti che possiamo utilizzare direttamente in una DataMap, ad esempio impostando la proprietà collection.

$photosDM.collection = b.results.photo;

In questo esempio $photosDM è una DataMap che contiene documenti di tipo Photo. La classe di questo documento viene creata durante l’importazione della Web API di Unsplash.

Infine nell’evento onRowComposition della DataMap andremo ad impostare la proprietà src di un elemento immagine ad uno dei valori contenuti nel documento come si vede nel codice seguente:

let photoDoc = row.document;
$image.src = photoDoc.urls.small;

Utilizzando le API in formato OpenAPI è quindi sufficiente qualche riga di codice per ottenere una videata in grado di mostrare una lista di immagini che corrisponde ai criteri di ricerca inseriti dall’utente.