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.