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 riportate le specifiche necessarie ad implementare nei propri sistemi l'utilizzo delle interfacce tecniche di tipo REST.

Nella pagina vengono indicati i Servizi REST della componente Validator del SINFI.

 

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.

 

Le chiamate dovranno contenere il parametro relativo al token acquisito al login, un esempio:

iPlanetDirectoryPro = AQIC5wM2LY4SfcyZyTAIvJ5SHeLvxL7aMeydFSQkUI5MSo0.*AAJTSQACMDEAAlNLABM4ODc0NDEwNjk0MDAyNzkxODA0AAJTMQACMDg.*

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

 

TABELLA DEI SERVIZI

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.

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

 

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    

 

 

DOCUMENTAZIONE COMPLETA CON ESEMPI

All'interno della documentazione, 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.