Lo scopo di questo articolo è quello di mostrare il lavoro fatto per permettere l’accesso web a Smeup ERP tramite l’utilizzo del protocollo HTTP. Sono stati sviluppati due progetti riferiti alle seguenti tecnologie: REST API e GraphQL. Questo articolo sarà quindi suddiviso in due parti per mostrare la loro implementazione.

Cos’è REST API

REST API è uno stile architetturale ormai conosciuto nell’ambito informatico ed utilizzato da anni per l’accesso ai dati via HTTP.  Questa tecnologia, si basa su un semplice concetto: si esegue una richiesta HTTP di dati e si riceve come risposta i dati stessi (o risorse) in un formato prestabilito. La richiesta HTTP viene fatta sotto forma di URL, ossia un indirizzo web. Gli attori coinvolti sono:

  • Il client: chi esegue la richiesta di risorse
  • Il server: chi riceve la richiesta tramite un servizio web e fornisce le risorse

Con questo protocollo, le richieste possono essere di diversa natura e vengono identificate dai “VERBI”. Elenco di seguito solo le operazioni più comuni:

  • GET: lettura
  • POST: scrittura
  • PUT: aggiornamento
  • DELETE: cancellazione

Vi è quindi un legame stretto tra richiesta e risposta: per ogni richiesta esiste una corrispondente risposta. Le richieste http vengono preventivamente definite nel servizio web. In Smeup è stato creato un prototipo in cui i dati vengono forniti con un formato JSON, quindi il clint dovrà, una volta ricevuta la risposta, deserializzare la stringa JSON in un oggetto per interpretare la risposta ricevuta.

Struttura di un’applicazione REST API

Le applicazioni sono normalmente formate da programmi ed da un database dove ogni tabella corrisponde ad un’entità logica: clienti, articoli etc. Dovendo creare una REST API che permetta di accedere ai dati dall’esterno tramite HTTP, in queste situazioni si fanno tanti endpoint (richieste) quante sono le tabelle moltiplicati per il numero di verbi che si vogliono mettere a disposizione. Supponiamo di volere permettere di eseguire tutte e 4 le operazioni sopra elencate per 2 tabelle che sono clienti ed articoli. In questa situazione gli endpoint totali saranno: 2 (clienti e fornitori) x  4 (operazioni) = 8 endpoint in totale. E’ importante comprendere da subito l’endpoint (o richiesta) è una funzione del servizio web che riceve la richiesta e restituisce la risposta. Gli URL di questi endpoint potrebbero essere ad esempio:

curl GET http://localhost/clienti
curl POST http://localhost/clienti
curl PUT http://localhost/clienti
curl DELETE "http://localhost/clienti
curl GET http://localhost/articoli
curl POST http://localhost/articoli
curl PUT http://localhost/articoli
curl DELETE "http://localhost/articoli

Ognuno di questi endpoint esegue operazioni diverse poiché si tratta di tabelle diverse.

L’implementazione di Smeup

Come è già stato spiegato anche in altri articoli riguardanti il gestionale, l’ERP di Smeup non ha un database statico, quindi formato da tabelle ognuna delle quali contenenti specifiche informazioni (es. clienti, articoli.. etc), ma oggetti generici a cui si può accedere tramite dei servizi del Provider di Smeup. Quest’architettura ha avuto alcuni importanti impatti che hanno condizionato lo sviluppo di quest’applicazione:

  • Il servizio web non può accedere direttamente ai dati.
  • Le richieste devono contenere: il nome della risorsa a cui si riferiscono.
  • Esiste un servizio del provider per ogni tipo di verbo (o quasi)

Se ad esempio si richiede l’elenco dei clienti o degli articoli si utilizzerà un endpoint del servizio web che a sua volta, utilizzerà il servizio LOA10_SE del provider. Se invece si vuole inserire, modificare o eliminare un cliente o un articolo, il servizio web utilizzerà il servizio LOA40_SI del provider. In questa situazione gli endpoint totali saranno: 1 (clienti e articoli) x  4 (operazioni ) = 4 endpoint in totale. E’ evidente,  che a parità di operazione, è possibile creare un unico endpoint, in grado di restituire la risposta per ogni entità. Questo perché il nome dell’entità (clienti, articoli etc) viene passato come parametro. Gli URL di questi endpoint potrebbero essere ad esempio:

curl GET http://localhost/apiservice/api/services/entity-management/customers (oppure items)
curl POST http://localhost/apiservice/api/services/entity-management/customers (oppure items)
 curl PUT http://localhost/apiservice/api/services/entity-management/customers (oppure items)
 curl DELETE http://localhost/apiservice/api/services/entity-management/customers (oppure items)

In questi endpoint, “customer” e “items” sono soltanto dei parametri che vengono passati all’endpoint stesso.

Questo meccanismo ha facilitato di molto lo sviluppo dell’API REST, perché ci si è focalizzati sulle operazioni che l’endpoint doveva eseguire piuttosto che sulle entità stesse o sui loro campi nel database. Il numero di endpoint, si è ridotto a 4 e sono utilizzabili per tutte le entità.

Perché usare Smeup API REST

struttura

Dato che il servizio REST API non fa altro che da ponte tra l’http client ed i servizi del Provider di Smeup(proxy), ci si potrebbe chiedere le motivazioni che spingono ad utilizzarlo anziché fare uso dei dati forniti direttamente dal Provider di Smeup.

La ragione di tutto questo sta nel modo in cui i proxy di Smeup comunicano. Essi infatti, untilizzano una sintassi basata sulle FUN. Ogni FUN permette di eseguire un comando riferito ad un’oggetto di Smeup (clienti, articoli etc). Tuttavia, la sintassi delle FUN è molto complessa ed i nomi dei campi delle entità sono dei codici alfanumerici difficili da comprendere. Si è quindi pensato di mappare sia i nomi delle entità sia quelli dei campi, in modo da renderli parlanti ed intuitivi.

E’ stata aggiunta l’interfaccia utente di Swagger per facilitare l’esecuzione delle richieste con OpenApi.

swagger REST API

Come si può vedere nell’immagine sopra, c’è anche un bottone “Authorize” tramite il quale si può inserire la password che permette di usufruire dei servizi. Oltre ai 4 endpoint canonici, è stata aggiunta un’altra GET “Get Entity by Id” che, come dice il nome, permette di recuperare una certa risorsa tramite un campo chiave (questo endpoint usa il servizio B£SER_09). A scopo dimostrativo vedremo questo endpoint in dettaglio.

getbyid

In ogni endpoint è necessario selezionare il nome dell’entità (entity-type). Essendo un prototipo, non sono state previste tutte le tabelle ma solo le seguenti:

  • Collaborators (CNCOL)
  • Customers (CNCLI)
  • Items (ARART)
  • Projects (TACPG)
  • Todo (H3£TDO)

In questo endpoint, si deve inserire obbligatoriamente il campo della chiave (entity-key) che corrisponde alla chiave del record da cercare.  E’ anche possibile impostare una lista di campi da selezionare per ridurre la dimensione della risposta.

Di seguito è stata riportata un’immagine contenente una parte della risposta.

getbyid response

Vantaggi di Smeup API REST

Nella risposta ci sono alcune informazioni riguardanti la richiesta contenute nel tag “messages” oltre alla risposta vera e propria contenuta nel tag “payload”. Come si può notare, uno dei campi è stato restituito con il nome parlante: “CityCodeDescription” anziché il nome reale “D_I/57”. Questa mappatura dei nomi dei campi è il benefit dell’utilizzo delle REST API. Essendo un prototipo, non sono stati mappati tutti i nomi poiché serviva solamente dimostrare che il sistema funzionava.

Il client, seleziona l’entità “Collaborators” anziché CNCOL e riceve il campo “CityCodeDescription” anziché il nome reale “D_I/57”. Inoltre, la chiamata avviene tramite uno standard di comunicazione come HTTP del REST API anziché utilizzare una FUN.

La stessa chiamata eseguita con il Provider di Smeup ha la seguente sintassi:

“F(EXB;B£SER_09;OAV.INT) 1(CN;COL;COSANT) P(Det(*)) ”

Sostituzione del servizio “A39”

Un altro utilizzo del REST API è stato quello rendere disponibile via HTTP il servizio A39 del Provider di Smeup.

a39

Il servizio A39 è sostanzialmente un programma che contiene un elenco di abbinamenti tra codici e FUN. L’utente, anziché richiamare la FUN con la sintassi complicata mostrata precedentemente, chiama questo servizio passando semplicemente un codice. Il programma recupera la FUN corrispondente al codice, la esegue e restituisce il risultato.

Sul REST API, questi codici sono stati chiamati “action”. L’elenco delle action viene caricato quando si avvia l’applicazione. Dopo l’avvio, è quindi possibile eseguire i seguenti endpoint:

  • actions: restituisce l’elenco delle azioni e le corrispondenti FUN.
  • action: restituisce una singola action e la corrispondente FUN.
  • runAction: esegue la FUN collegata all’azione il cui codice è stato passato come parametro.
  • reloadActions: ricarica l’elenco delle azioni (utile nel caso fosse cambiato nel backend)

In questo gruppo le API sono state utilizzate per recuperare le informazioni sui contatti all’interno del Gmail Addon, dato che all’interno di Gmail Script non si poteva utilizzare il Provider.

A scopo dimostrativo, vedremo in dettaglio l’endpoint “runAction”.

runaction

In questo esempio richiamiamo l’azione “TOOLTIP1” che corrisponde ad uno script del backend che viene riportato di seguito.

tooltip1

I parametri sono variabili e specifici per ogni codice azione. Per questo motivo, devono essere passati sotto forma di oggetto JSON. In questo caso, vengono richiesti i dati di un TODO. Segue l’immagine della risposta.

runaction response

 

Conclusioni

Il REST API apre la strada ad una migliore fornitura delle risorse di Smeup verso l’esterno. Il prototipo è stato creato con l’intento di dimostrare le potenzialità di questo strumento ma, come avrete intuito, c’è ancora molto da sviluppare per rendere tutta l’architettura più stabile e funzionante.

Per permettere ad altri software di interrogare il nostro sistema con strumenti “universali” si doveva sfruttare la FUN che è lo strumento di comunicazione di Smeup. Tuttavia, data la loro complessità, le FUN sono state inglobate in un linguaggio universale e più comprensibile. Da qui è  iniziato il lavoro per nascondere i codici e mostrarli o riceverli come parole, fino ad arrivare all’utilizzo delle azioni che incorporano un intero script funzionale.

Essendo già orientati al concetto di entità e di servizio, Sme.UP ha permesso il riutilizzo delle logiche di gestione delle entitià. Alla fine il LOA10, il B£SER_09 ed il LOA40 (al netto che possano essere migliorati) implementano già di loro il CRUD e portano con sè il concetto di astrazione. Le API REST sono quindi state sollevate dalla necessità di accedere ai dati direttamente.

Nella seconda parte di questo articolo spiegheremo la seconda implementazione HTTP fatta con GraphQL.