Indice articolo

I Web Service vengono utilizzati per far comunicare diverse applicazioni che lavorano in linguaggi diversi e su piattaforme diverse utilizzando come ponte comune il protocollo HTTP.

Un esempio calzante potrebbe essere la necessità di far comunicare un’applicazione Java che gira su una macchina GNU Linux ed un’altra applicazione scritta in PHP che invece gira su una macchina Windows, oppure la necessità di dover fruire di dati che vengono gestiti da una particolare piattaforma e cercare di renderli disponibili nella propria. A questi scopi possono essere utilizzati i servizi messi a disposizione dai web service, di cui al momento esistono due tipi: SOAP e REST.
Nel seguito tratteremo della sola variante REST, ma attenzione, costruendo opportunamente l’xml soap di richiesta e interpretando correttamente la risposta, è tutto esattamente identico! Seguiranno degli articoli specifici.

HTTP: chiamate GET e POST

Come già accennato precedentemente il protocollo su cui si basano le comunicazioni REST è l’HTTP.
La fase di comunicazione alterna scambi di messaggi tra il client (che in questo caso è il provider Sme.UP) che è in grado di inviare richieste HTTP ed il server (che in questo caso è il WebService) che elabora la richiesta e restituisce una risposta. La risposta può essere una pagina HTML, un file JSON, un’immagine o qualsiasi altro formato. Nel nostro caso risponde con un JSON.

Le richieste da parte del client vengono effettuate attraverso due tipi di chiamate GET e POST.
La più utilizzata è sicuramente la GET che permette di veicolare tali richieste tramite query string, ovvero la capacità di aggiungere dei parametri da passare in input ad un’applicazione sul server “appendendole” all’URI inviato al momento della richiesta. Utilizzando questo metodo si dice che le informazioni vengono passate “in chiaro” siccome sono contenute direttamente e sono visibili nella chiamata.

Qui sotto possiamo vedere un esempio di chiamata GET utilizzando cURL, che non è altro che un software open source a riga di comando in grado di poter trasferire dati, ed in questo caso di inviare una chiamata HTTP.

ESEMPIO GET (utilizzando cURL)

curl \
 'https://www.googleapis.com/drive/v3/files?name=Titolo&mimeType=text/plain' \
 --header 'Authorization: Bearer [YOUR_BEARER_TOKEN]' \
 --header 'Accept: application/json'

Il metodo POST si differenza da GET in quanto i parametri della richiesta non vengono passati in query string e quindi non compaiono nell’URI ma vengono tenuti “in pancia” nella richiesta.

ESEMPIO POST (utilizzando cURL) 

curl --request POST \ 
'https://www.googleapis.com/drive/v3/files' \ 
--header 'Authorization: Bearer [YOUR_BEARER_TOKEN]' \ 
--header 'Accept: application/json' \ 
--header 'Content-Type: application/json' \ 
--data '{"name":"Titolo","mimeType":"text/plain"}'

Le richieste HTTP sono composte da un’intestazione (header) e da un corpo (body).
Gli header, che sono la parte iniziale del messaggio HTTP e ne esistono varie tipologie, si preoccupano di avvisare il server sulla tipologia del messaggio di richiesta inviato, cosa c’è all’interno del corpo, sul tipo di risposta preferita, ecc.. Sono composte da attributi nome-valore.
Nel nostro caso verranno quasi sempre utilizzati i soli header di richiesta (Content-Type) e di entità (Accept), che si occupano di fornire informazioni sul corpo del messaggio, e di avvisare il server circa il formato preferito di risposta.

Il body contiene l’eventuale struttura dati del POST.

Chiamate a WebService in 5 passi

1- La Ricerca

Il primo passo da compiere per poter interrogare delle API di qualsiasi webservice (pubbliche o private che siano) è proprio quello di analisi della documentazione, spesso denominata reference.

NB. Nel modo nelle aziende a cui ci approcciamo solitamente, l’interlocutore è un software terzo, per cui l’analisi delle API è solitamente sostituita da accordi e lavoro a quattro mani con il fornitore terzo.

Nel caso di API pubbliche, come nei nostri esempi, si tratta di mettersi alla ricerca di queste API e vedere se ciò che il servizio che stiamo per interrogare ci restituisce sono informazioni consone a ciò che cerchiamo.
Nella redazione di questo articolo ci affideremo alle API messe a disposizione da SAP, da Youtube e da DiscoGS (database di canzoni e vinili).

La ricerca della documentazione delle API messe a disposizione è davvero banale e richiede il minimo sforzo, infatti basterà cercare in un qualsiasi motore di ricerca la dicitura documentation <nomeServizio> API RESTful:

# Nel nostro caso:
"documentation Youtube API RESTful"
"documentation SAP API RESTful"
"documentation DiscoGS API RESTful"
SAP_API Youtube_API  discoGS_API

Nelle immagini soprastanti si ha la resa delle ricerche effettuate.
Ora non ci resta che creare un “collegamento” a queste API offerte da questi Web Service in Sme.UP!

2- Creazione dello script LOA38

Una volta effettuato questo semplicissimo step, ora si passa alla parte più divertente, in cui mettere mano al codice, ma anche in questo caso i nostri programmatori si sono adoperati per rendere la cosa il più semplice possibile. Vediamo come.

NB: Lo script che andremo a creare deve necessariamente:

  • essere chiamato con un nome del tipo “LOA38_XY” dove con “Y” ci si intente qualsiasi tipo di lettera/numero;
  • risiedere all’interno del path: LIBRERIA_PERSONALIZZAZIONI/SCP_SET/ così da avere  LIBRERIA_PERSONALIZZAZIONI/SCP_SET/LOA38_XY

Nei prossimi passaggi userò il nuovo editor di script di Web.UP, ma è possibile fare lo stesso con quello di Looc.UP.

Apriamo l’editor web, rechiamoci in alto a sinistra e clicchiamo sull’icona della cartella con il “+” avente come tooltip “New member“. A questo punto ci verrà richiesto di inserire gli estremi di posizionamento e nome dello script che intendiamo creare.
Scegliamo in che libreria metterlo (nel caso fossimo da un cliente la libreria da inserire è ad esempio quella delle personalizzazioni, nel mio caso la inserisco nella mia cartella di lavoro W_SCIMAM), come file inseriamo “SCP_SET” e come nome del file un membro che sia scritto come nelle note ad inizio capitolo “LOA38_XY” dove Y è o un numero o una lettera.

editor_vuoto salvataggio salvataggio_ok

Nel caso avessimo effettuato tutti i passi correttamente la pagina dovrebbe somigliare all’ultima figura, in cui viene visualizzato in rosa il path effettivo di dove verrà salvato il file.
Come detto precedentemente, i nostri programmatori hanno facilitato l’aggiunta di nuove righe di codice inserendo degli “snippet” all’interno del nuovo terminale, che ci consentiranno di modificare del codice già preformattato, aumentando così la produttività e riuscendo a ridurre al minimo il rischio di errori.

Clicchiamo quindi sulla prima riga del terminale e clicchiamo i tasti   ctrl + spazio.
Così facendo si aprirà una “tendina” con all’interno degli shortcut per poter utilizzare lo snippet già pre-configurato.
Scegliamo di creare per prima cosa la coda del provider cliccando sul relativo nome e la conseguenza sarà visualizzare queste righe di codice

editor_coda_provider editor_snippet_coda

L’unica incombenza che si lascia al lettore è quella di rinominare i campi che vengono scritti tra i delimitatori “@_” e “_@” (delimitatori compresi).
In questo caso il campo che bisogna editare è quindi il DtaQ in cui andrà inserita la coda del provider che si occuperà di “far girare” il nostro script.
Nel mio caso è la coda PROTST, ma nel caso del lettore evidentemente è diversa da provider a provider.

E' importante ricordare che lo snippet "Coda Provider" va inserito solo all'inizio dello script.
Possono quindi coesistere più sezioni richiamate con lo snippet "Web Service Rest" ma la coda del provider può comparire UNA ed UNA sola volta all'interno di esso (ed ad inizio file).

Si passa poi ad inserire il secondo snippet. La procedura è la medesima eseguita precedentemente, ovvero cliccare i tasti  .
Stavolta lo snippet da scegliere è quello per la creazione del collegamento per Web Service Rest.

editor_webservice

Come prima, modifichiamo solo le parti racchiuse dai delimitatori (delimitatori compresi).
Diamo quindi un codice ed una descrizione alla SEZ,  inseriamo poi l’URL della chiamata che dovrà essere effettuata verso il server che offre il servizio REST.
E’ possibile inserire anche delle variabili all’interno dell’URL che verranno riempite dinamicamente prima della chiamata. La sintassi per le variabili é formata da una parte fissa e da una parte variabile che identifica il nome della variabile che andrà riportata nelle SUBVAR:

[A38.NomeVariabile]

Il passo successivo sarà quello di dare un codice ed una descrizione alla SUB e alla SUBMET che identificano rispettivamente una subsezione ed un metodo della subsezione.

Arriviamo in fine alla parte delle variabili. Ci sono principalmente due tipi di variabili: header e interne.
Quelle di tipo header sono quelle che vengono inserite nell’header di una richiesta HTTP, mentre quelle interne sono le variabili che andranno a sostituire il loro valore all’interno dell’URL precedentemente inserito.
Bisogna quindi assegnare un nome alla variabile che deve essere univoco ed una breve descrizione. Il parametro TpVar identifica la tipologia delle variabili, mentre il parametro DftVal identifica il valore di default della variabile nel caso ne avesse uno.
Se tutto è stato completato correttamente si dovrebbe avere una soluzione simile a quella raffigurata nell’immagine sottostante. Nel mio caso ho deciso di effettuare una chiamata a delle API di DiscoGS che mi permetteranno di ricercare tutte le informazioni riguardo al nome di un artista che verrà inserito.

editor_compiled_pixel

Non ci resta quindi che salvare il file con il pulsante appropriato (icona a forma di Floppy disk con tooltip “Save” o con la pressione dei tasti   ctrl + alt+ w.

3- Riavvio del framework del Provider

A questo punto dato che si è creato un nuovo script che deve essere caricato sulla coda del provider (che è quello scritto in precedenza nello script), sarà necessario aggiornare il framework della gestione del LOA38 (che è quello che gestisce la parte dei servizi REST).

Rechiamoci dunque nella scheda per il riavvio del framework digitando nello spotlight:

O V3 LSE [nomeProvider]

nel mio caso:
O V3 LSE PROTST

Nel menu laterale scegliere LOA38, dopodichè “Ricarica Network“.

PROTST
A questo punto, dopo un’attesa di qualche decina di secondi sarà possibile visualizzare nell’albero Network anche il nostro script stando a significare che esso è stato caricato in memoria pronto ad essere eseguito.

4- Avvio servizio interrogazione WebService

Arrivati a questo punto siamo arrivati al traguardo. Saremo ora in grado di testare il nostro lavoro attraverso una chiamata K11 e goderci il risultato.
Tramite lo spotlight rechiamoci quindi sulla scheda del LOA38, scrivendo semplicemente:

SCH LOA38

Nella barra laterale sinistra ricerchiamo il codice (o più facilmente la descrizione) che avevamo dato al nostro script (Nel mio caso lo script X1 con sezione S23 e subsezione B00) ed esplodere l’albero fino a trovare la subsezione desiderata (Punto 1 della figura sottostante).
Successivamente scorrere la pagina e cliccare su “Verifica con K11” (Punto 2 della figura sottostante)


Così facendo si aprirà una lista di campi compilabili.
Nella combo-box “Funzione Metodo” scegliamo l’opzione “SND.FIL” (che sta per Send File) che in questo caso è una richiesta che parte da un server per arrivare ad un WebService.
I due campi successivi sono utili nel caso dovessimo effettuare richieste POST, ove è necessario indicare un body  da inviare.
E’ possibile scegliere due strade: nel caso il body sia molto lungo (superiore ai 150 caratteri) è possibile scriverlo in un file su AS e indicare il path IFS relativo ad esso nel campo “Percorso IFS“. Nel caso invece di body di piccole dimensioni, utilizzato di solito per la fase di test, è possibile utilizzare il campo “Stringa Payload” in cui è possibile inserire il testo in formato RAW.
Nel nostro caso entrambi i campi al momento non servono dato che stiamo effettuando una chiamata GET.
Si passa poi alla compilazione delle variabili che abbiamo precedentemente inserito nello script. Come è possibile notare avendo definito nello script sia “Content-Type” che “Accept” è OBBLIGATORIO definirli entrambi (Punti B e C della figura sottostante).
In entrambi i casi avevamo definito il default value così da non dover compilare il valore di tali variabili ed infatti nel Punto B così è stato fatto. Il Punto C  pur avendo il default value (e quindi avremmo potuto lasciare in bianco il valore di tale campo) a scopo didattico si è dimostrato che è possibile sovrascrivere tale valore (Punto C1)

N.B: Ricorda che:
- nel caso  si metta un valore di default alle variabili, esse devono OBBLIGATORIAMENTE essere scritte, ma non è necessario ripetere tale valore perchè verrà automaticamente caricato dal framework. E' però possibile comunque cambiarne il valore "al volo".
 - non è invece possibile inserire variabili che non siano state precedentemente dichiarate all'interno dello script di configurazione.

Si è poi passati alla compilazione dell’unica variabile interna in cui gli viene dato come valore il nome dell’artista da cercare (Punto D).
Una volta confermata la chiamata dopo alcuni attimi ecco ricevere la risposta in formato Json in formato raw, ma che tramite un semplice click su “Json web” permette di visualizzare comodamente la risposta appena ricevuta in maniera più Human-friendly.

risultato_loa38 risultato_web_loa38

Nel caso non si sapesse come gestire un Json o semplicemente cosa fosse un file Json, si rimanda alla lettura dell’articolo “Ecco Json.UP, tenetevi forte.”  :

http://blog.smeup.com/webservice-json/

Non resta quindi sbizzarrirsi alla ricerca di WebService da agganciare a Sme.UP, così da poter essere interrogati e facilmente fruiti dalla nostra piattaforma!