In questo paragrafo vediamo come utilizzare una Web API REST generica, così definita in quanto non utilizza uno specifico standard semantico per le chiamate. In questi casi, il metodo di utilizzo è semplice: si crea un’istanza di url che rappresenta l’endpoint della Web API e si utilizzano i metodi get e post per recuperare o inviare dati.
Esecuzione di una chiamata get #
Vediamo un esempio di come recuperare dati da una Web API REST. Verrà utilizzato un endpoint di test che espone i dati della tabella Employees del database NorthWind.
let endpoint = "https://examples.instantdevelopercloud.com/
datamapdesignpatterns/Employee";
let u = app.fs.url(endpoint);
//
let options = {
authentication : {
username:”alladin”,
password:”opensesame”
}
};
//
let resp = yield u.get(options);
let ok = resp.status === 200;
if (ok) {
let data = JSON.parse(resp.body);
let emplist = data.value;
//
for (let i = 0; i < emplist.length; i++) {
let emp = emplist[i];
console.log(emp);
}
}
//
return ok;Dopo aver effettuato la chiamata get all’endpoint, passando i parametri per l’autenticazione basic richiesti dall’endpoint, è opportuno controllare il codice di ritorno che solitamente è 200 quando l’operazione ha avuto successo.
A questo punto la risposta, che è in formato JSON come comunemente accade, viene trasformata in oggetto e viene estratto l’array dei dati degli impiegati. In questo esempio i dati vengono semplicemente stampati nella console, ma possono anche essere caricati in una datamap o in una collection.
Esecuzione di una chiamata post #
Per modificare i dati vengono normalmente utilizzati i metodi post, patch e delete. Siccome stiamo trattando di Web API generiche, per sapere quale metodo utilizzare in base all’operazione richiesta occorre fare riferimento alla documentazione della Web API.
Nell’esempio seguente utilizziamo il metodo post per creare un nuovo impiegato, utilizzando sempre l’endpoint precedente.
let endpoint = "https://examples.instantdevelopercloud.com/
datamapdesignpatterns/Employee";
let u = app.fs.url(endpoint);
//
let authdata = {
username:”alladin”,
password:”opensesame”
};
let body = {
EmployeeID : 444,
FirstName : ”Giuseppe”,
LastName : “Ferrari”,
Title : ”Sig”,
Country : ”Italia”,
Notes : “Corre veloce”
}
//
let resp = yield u.post({
authentication: authdata,
body: body
});
if (resp.status !== 201) {
let data = JSON.parse(resp.body);
console.log(“errore”, data.error);
}Dopo aver inviati i dati del nuovo impiegato all’endpoint occorre controllare la risposta per verificare se l’operazione ha avuto successo o sono avvenuti degli errori.
Web API e documenti #
Il modo migliore per utilizzare chiamate a Web API esterne è quello di inserire il codice di recupero dati o di invio delle modifiche all’interno di una classe documento.
In questo modo l’applicazione potrà interagire con il documento, senza avere conoscenza di come il documento viene permanentizzato, cioè letto o scritto in un data store. Si aumenta così il livello di incapsulamento del sistema.
I documenti favoriscono questa modalità di utilizzo delle Web API attraverso gli eventi beforeLoad e onSave.
L’evento beforeLoad permette di intercettare le chiamate ai metodi di caricamento dati (loadByKey, loadCollection, collection.load) e sostituirli con chiamate a Web API, restituendo poi i risultati trovati nel parametro collection. Il tipo di caricamento richiesto viene passato nel parametro options.loadType, mentre i filtri di caricamento sono presenti nelle proprietà del documento a cui viene notificato l’evento.
L’evento onSave permette di intercettare le fasi di salvataggio del documento e sostituirle con chiamate Web API. A seconda della modalità prevista dalla Web API, è possibile intercettare la fase di beforeSave, oppure quella di inserting, updating e deleting. Si ricorda di impostare a true la proprietà options.skip che permette di disabilitare il salvataggio nel database eseguito dal framework.