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.
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
Servizio | Descrizione | Base URL | Parametri |
Login | Consente l’autenticazione degli users tramite generazione di un SSO Token riutilizzabile per accedere a tutti i servizi esposti | https://www.sinfi.it/sso/json/authenticate | X-OpenAM-Username, X-OpenAM-Password passati tramite header request http |
Upload ZIP file | Invia al Validator un file zip contenente una serie di ESRI-Shape file SINFI compliant | https://www.sinfi.it/sinfi-validator1/rest/upload |
File-POST byte[] stream |
Ritorna la lista delle Richieste | Lista delle richieste effettuate |
https://www.sinfi.it/sinfi-validator1/rest/lista-richieste/{tipo} https://www.sinfi.it/sinfi-validator1/rest/lista-richieste/ALL |
GET {tipo}=ALL |
Ritorna le indicazioni dei file |
Fornisce Indicazione dei files legati al singolo codice richiesta, in ordine alle fasi di check disponibili NOTA: l’id è da prendere all’interno dell’output fornito da ../rest/lista-richieste/{tipo} |
https://www.sinfi.it/sinfi-validator1/rest/lista-file-richieste/{id} https://www.sinfi.it/sinfi-validator1/rest/lista-file-richieste/538 |
GET {id}=538 |
Servizio CSV per la Struttura file | Ritorna info sulle fasi di validazione check di validazione. |
https://www.sinfi.it/sinfi-validator1/ rest/csv/{id}/{csv}?offset=<val>&limit=<val> https://www.sinfi.it/sinfi-validator1/rest/csv/532/geometryerror?offset=0&limit=1000 |
GET {id}=532 {csv}= geometryerror offset=0&limit=1000 |
Report XLSX | Ritorna un report XLSX per l’ID Richiesta specificato |
https://www.sinfi.it/sinfi-validator1/rest/report-excel/{id} https://www.sinfi.it/sinfi-validator1/rest/report-excel/541 |
GET {id}=541 |
Report PDF |
Ritorna un report PDF per l’ID Richiesta specificato e per la modalità sintetico/analitico disponibile come indicato da ../rest/lista-richieste/{tipo} |
https://www.sinfi.it/sinfi-validator1/rest/report/{type}/{id} https://www.sinfi.it/sinfi-validator1/rest/report/sintetico/538 |
GET {type}=sintetico {id}=532 --- *{type}=[sintetico/analitico]
|
Report DB | Ritorna File .zip contenente il report |
https://www.sinfi.it/sinfi-validator1/rest/reportdb/{id} https://www.sinfi.it/sinfi-validator1/rest/reportdb/541 |
GET {id}=541 |
Lista SHP | E’ ottenuta una lista riferimenti a Shape in formato JSON | https://www.sinfi.it/sinfi-validator1/rest/lista-shapefile |
GET
|
Storico Aggiornamenti |
Lista JSON con lo storico e gli attributi relativi agli aggiornamenti
|
https://www.sinfi.it/sinfi-validator1/rest/history/{id} https://www.sinfi.it/sinfi-validator1/rest/history/538 |
GET {id}=538
|
Download Zip Relativo all’ID indicato |
Ritorna lo zip relativo all’id selezionato, in caso di indisponibilità dello stesso, il testo: <<Errore file non più recuperabile>> |
https://www.sinfi.it/sinfi-validator1/rest/zip/{id} https://www.sinfi.it/sinfi-validator1/rest/zip/538 |
GET {id}=538 |
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:
Stato | Trascodifica | Stato | Trascodifica |
0 | uploaded | 5 | importer_success |
1 | tovalidate | 6 | importer_error |
2 | validate_success | 7 | approved |
3 | validate_error | 8 | not_approved |
4 | toimporter |
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-validator1/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-validator1/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-validator1/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-validator1/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-validator1/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-validator1/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-validator1/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-validator1/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-validator1/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-validator1/rest/zip/538
Headers:
Esempio di Risposta:
binario compatibile con il formato zip oppure messaggio <<Errore file non più recuperabile>>