Interfacce Tecniche SINFI (REST Services)

Al fine di favorire l'utilizzo di protocolli M2M (Machine to Machine), in grado di agevolare ed automatizzare alcuni processi essenziali per il conferimento dei dati al SINFI, di seguito vengono riportati le specifiche necessari ad implementare nei propri sistemi l'utilizzo delle interfaccie tecniche di tipo REST.

Nella pagina vengono indicati i Servizi REST della componente Validator del SINFI ed in calce le istruzioni per l'utilizzo in WFS e WMS.

Di seguito viene riportata una tabella riepilogativa di tutti i servizi esposti riportante un sunto sulle funzionalità degli stessi e dei loro modi di accesso. Importante, si riterrà implicito che in tutti i casi di chiamata i client debbano fornire ai servizi il token OpenAM precedentemente ottenuto tramite la chiamata al servizio di Login.

La chiamata dovrà aggiungere ai parametri previsti dal suo protocollo il parametro relativo al token, un esempio:

iPlanetDirectoryPro = AQIC5wM2LY4SfcyZyTAIvJ5SHeLvxL7aMeydFSQkUI5MSo0.*AAJTSQACMDEAAlNLABM4ODc0NDEwNjk0MDAyNzkxODA0AAJTMQACMDg.*

Il valore del token potrà essere ottenuto a valle della chiamata al servizio opportuno, al servizio di login.

TABELLA DEI SERVIZI

Esempi di Chiamata e risultato atteso.

Riferendosi alla tabella prima esposta, per ogni Servizio verrà illustrato un esempio di chiamata e il corrispettivo output atteso. Si Ricorda che l’esempi sono riportati per un immediato utilizzo all’interno dell’applicativo Postman.

Un flusso sequenziale tipico delle chiamate è il seguente:

1) Servizio Upload -> ritorna attributi md5, nomefile

2) Chiamata /rest/lista-richieste -> ritorna un json con array di oggetti con attributi, tra cui md5, nomefile e id. Il chiamante effettua il parser dell’array usando md5 o nomefile come chiave di ricerca, individuando il record opportuno viene letto l’id da riutilizzare in tutte le chiamate a seguire

3) Utilizzo dell’id per le altre chiamate REST ove necessario.

E’ utile inoltre per l’opportunità e le tempistiche di tali chiamate leggere da /rest/lista-richieste anche l’attributo "stato", di seguito la trascodifica:

Flusso sequenziale di chiamate per i check post-validazione:

1) Chiamata /rest/lista-file-richieste/{id} -> json con lista codici relative a tipologie di check

2) Chiamata a /rest/csv/{id}/{csv}?offset=<value>&limit=<value> sostituendo la specifica tipologia di check a {csv} ed utilizzando il relativo id

Servizio di Login ed Autenticazione

Consente l’autenticazione degli users tramite generazione di un SSO Token riutilizzabile per accedere a tutti i servizi esposti. Come detto è il primo servizio da invocare per ottenere il token da riutilizzare nelle successive chiamate ai vari servizi supportati dal SINFI.

Esempio di Chiamata:

curl -k --request POST --header "X-OpenAM-Username: USERNAME" --header "X-OpenAM-Password: PASSWORD" --header "Content-Type: application/json" "https://www.sinfi.it/sso/json/authenticate"

Esempio di Risposta:

{"tokenId":"AQIC5wM2LY4SfcyZyTAIvJ5SHeLvxL7aMeydFSQkUI5MSo0.*AAJTSQACMDEAAlNLABM4ODc0NDEwNjk0MDAyNzkxODA0AAJTMQACMDg.*","successUrl":"https://www.sinfi.it"}

Sostituendo nella chiamata la propria user e password, si ottiene un json dal quale e possibile ricavare il token per il suo riutilizzo.

Upload ZIP file

Invia al Validator un file zip contenente una serie di ESRI-Shape file SINFI compliant.

ATTENZIONE: Il token deve essere ottenuto tramite:

curl -k --request POST --header "X-OpenAM-Username: USERNAME " --header "X-OpenAM-Password: PASSWORD" --header "Content-Type: application/json" "https://www.sinfi.it/sso/json/authenticate",

oppure con apposita chiamata Postaman

Esempio di Chiamata curl :

Modo: POST - https://www.sinfi.it/sinfi-validator/rest/upload

Body – Form data

key: file - value:finename.zip

Esempio di Risposta:

{

   "messaggioOk": "L'identificatvo della transazione è: USERNAME.1516708353715",

   "md5": "99ecc9b4722ed44efccf5d4bcb7e283f"

}

Ritorna la lista delle Richieste

Il dato riporta un json a guisa di catalogo, nel quale è possibile estrarre attributi da utilizzare per altre chiamate REST, come l’”id”, “sintetico”/”analitico”, “stato” et al.

Esempio di Chiamata:

Modo: GET - https://www.sinfi.it/sinfi-validator/rest/lista-richieste/ALL

Headers:

Esempio di Risposta:

JSON

{

   "data": [

       {

           "id": 541,

           "nome_shapefile": "ZZZDAP15I12N505M.GRUPPO_SOCIETA.1516347598181",

           "stato": "6",

           "data_caricam": "2018-01-19 08:39",

           "data_elab": "2018-01-22 09:44",

           "userid": "USERNAME",

           "path_shapefile": "/cluster-share/validator/data/to-validate-dir/ZZZDAP15I12N505M.GRUPPO_SOCIETA.1516347598181/report/",

           "md5": "63067e2972e78935709f026f26793d60",

           "sintetico": true,

           "analitico": false,

           "excel": true,

           "userfile": "GRUPPO_SOCIETA_TLR_20171122.zip"

       },

….

Indicazioni tipologie check per i File

Fornisce Indicazione dei files legati al singolo codice richiesta.

NOTA: l’id è da prendere all’interno dell’output fornito da ../rest/lista-richieste/{tipo}

L’attributo “codice” è da riutilizzare nella chiamata a servizio rest/csv/{id}/{csv}?offset=<val>&limit=<val>

in luogo di {csv}

Esempio di Chiamata:

Modo: GET - https://www.sinfi.it/sinfi-validator/rest/lista-file-richieste/541

Headers:

Esempio di Risposta:

{

   "files": [

       {

           "codice": "attributestructure",

           "label": "attributestructure"

       },

       {

           "codice": "elementstate",

           "label": "elementstate"

       },

       {

           "codice": "elementstatedbf",

           "label": "elementstatedbf"

       },

       {

           "codice": "elementstatedbn",

           "label": "elementstatedbn"

       },

…..

Servizio CSV per la validità di Struttura file

Ritorna info sulla tipologia di validazione check specificata.

Esempio di Chiamata:

Modo: GET - https://www.sinfi.it/sinfi-validator/rest/csv/387/geometryerror?offset=0&limit=1000

Headers:

Esempio di Risposta:

{"totalCount":0,"header":null,"body":null}

Download Report XLSX

Ritorna un report XLSX per l’ID Richiesta specificato. Su postman opzionalmente specificare Send and Download per non visualizzare lo stream byte[] ma piuttosto salvare in locale il file.

Esempio di Chiamata:

Modo: GET - https://www.sinfi.it/sinfi-validator/rest/report-excel/541

Headers:

Esempio di Risposta:

Stream binario compatibile con xlsx

Download Report PDF

Ritorna un report PDF per l’ID Richiesta, come per il type  [sintetico/analitico] disponibile come indicato da ../rest/lista-richieste/{tipo}. Su postman opzionalmente specificare Send and Download per non visualizzare lo stream byte[] ma piuttosto salvare in locale il file.

Esempio di Chiamata:

Modo: GET - https://www.sinfi.it/sinfi-validator/rest/report/sintetico/538

Headers:

Esempio di Risposta:

Stream binario compatibile con PDF

Download Report DB (formato zip)

Ritorna un file Zip contenete il Report DB per l’ID Richiestacome indicato da ../rest/lista-richieste/{tipo}. Su postman opzionalmente specificare Send and Download per non visualizzare lo stream byte[] ma piuttosto salvare in locale il file.

Esempio di Chiamata:

Modo: GET - https://www.sinfi.it/sinfi-validator/rest/reportdb/541

Headers:

Esempio di Risposta:

Stream binario compatibile con formato file ZIP

Lista degli Esri-SHP

Viene restituita una lista riferimenti a Shape in formato JSON.

Esempio di Chiamata:

Modo: GET - https://www.sinfi.it/sinfi-validator/rest/lista-shapefile

Headers:

Esempio di Risposta:

{

   "files": [

       {

           "name": "GRUPPO_SOCIETA",

           "creationDate": "2017-10-03 12:50",

           "modificationDate": "2017-10-03 12:50"

       },

       {

           "name": "GRUPPO_SOCIETA",

           "creationDate": "2017-11-28 14:09",

           "modificationDate": "2017-11-28 14:09"

       },

       {

           "name": "GRUPPO_SOCIETA",

           "creationDate": "2017-11-28 14:16",

           "modificationDate": "2017-11-28 14:16"

       },

       {

           "name": "GRUPPO_SOCIETA",

           "creationDate": "2017-11-29 08:51",

           "modificationDate": "2017-11-29 08:51"

       },

       {

           "name": "GRUPPO_SOCIETA",

           "creationDate": "2017-11-29 08:51",

           "modificationDate": "2017-11-29 08:51"

       },

…..

Lista History degli aggiornamenti

Lista JSON con lo storico e gli attributi relativi agli aggiornamenti per l’ID Richiesta come indicato da ../rest/lista-richieste/{tipo}., il formato restituito è JSON

Esempio di Chiamata:

Modo: GET - https://www.sinfi.it/sinfi-validator/rest/history/538

Headers:

Esempio di Risposta:

{

   "storico": [

       {

           "id": 538,

           "stato": "0",

           "dataAggiornamento": "2018-01-15 14:56",

           "log": null

       },

       {

           "id": 538,

           "stato": "1",

           "dataAggiornamento": "2018-01-16 07:21",

           "log": null

       },

…

Download ZIP File

Ritorna lo zip relativo agli aggiornamenti per l’ID Richiesta come indicato da ../rest/lista-richieste/{tipo}., il formato binario compatibile con lo zip oppure un messaggio di disponibilità: <<Errore file non più recuperabile>>

Esempio di Chiamata:

Modo: GET - https://www.sinfi.it/sinfi-validator/rest/zip/538

Headers:

Esempio di Risposta:

binario compatibile con il formato zip oppure messaggio <<Errore file non più recuperabile>>

WMS e WFS

Step 1) Ottenere con chiamata REST il file xml delle Capabilities-> https://www.sinfi.it/geoserver/ows?service=wfs&version=2.0.0&request=GetCapabilities   -> da qui individuare il lyr WFS desiderato (convenzione nomelyr-> ws:namelyr)

Step 2) dal nome lyr compongo chiamata ogc wfs https://www.sinfi.it/geoserver/<workspace>/ows?service=WFS&version=1.0.0&request=GetFeature&typeName=<nomelyr>&maxFeatures=50&outputFormat=application%2Fjson

Esempio layer 

<<sinfi_ente:infr_rt_estensione_l>> (identificato all'interno xlm Capabilities)

la chiamata è così formata

https://www.sinfi.it/geoserver/sinfi_ente/ows?service=WFS&version=1.0.0&request=GetFeature&typeName=sinfi_ente:infr_rt_estensione_l&maxFeatures=50&outputFormat=application%2Fjson

NOTA: IL PARAMETRO outputFormat consenti il "download" del formato desiderato tra SHP, GeoJSON, KML e gli altri previsti da geoserver