Interfacce tecniche (REST)

Interfacce tecniche (REST)

Interfacce tecniche (REST)

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.

ServizioDescrizioneBase URLParametri
LoginConsente l’autenticazione degli users tramite generazione di un SSO Token riutilizzabile per accedere a tutti i servizi espostihttps://www.sinfi.it/sso/json/authenticateX-OpenAM-Username, X-OpenAM-Password passati tramite header request http
Upload ZIP fileInvia al Validator un file zip contenente una serie di ESRI-Shape file SINFI complianthttps://www.sinfi.it/sinfi-validator1/rest/uploadFile-POST byte[] stream
Ritorna la lista delle RichiesteLista delle richieste effettuatehttps://www.sinfi.it/sinfi-validator1/rest/lista-richieste/{tipo} https://www.sinfi.it/sinfi-validator1/rest/lista-richieste/ALLGET {tipo}=ALL
Ritorna le indicazioni dei fileFornisce 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/538GET {id}=538
Servizio CSV per la Struttura fileRitorna 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=1000GET {id}=532 {csv}= geometryerror offset=0&limit=1000
Report XLSXRitorna un report XLSX per l’ID Richiesta specificatohttps://www.sinfi.it/sinfi-validator1/rest/report-excel/{id} https://www.sinfi.it/sinfi-validator1/rest/report-excel/541GET {id}=541
Report PDFRitorna 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/538GET {type}=sintetico {id}=532 — *{type}=[sintetico/analitico]  
Report DBRitorna File .zip contenente il reporthttps://www.sinfi.it/sinfi-validator1/rest/reportdb/{id} https://www.sinfi.it/sinfi-validator1/rest/reportdb/541GET {id}=541
Lista SHPE’ ottenuta una lista riferimenti a Shape in formato JSONhttps://www.sinfi.it/sinfi-validator1/rest/lista-shapefileGET  
Storico AggiornamentiLista 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/538GET {id}=538  
Download Zip Relativo all’ID indicatoRitorna 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/538GET {id}=538

Un flusso sequenziale tipico delle chiamate è il seguente:

  1. Servizio Upload -> ritorna attributi md5, nomefile
    1. 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
    1. Utilizzo dell’id per le altre chiamate REST ove necessario.

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

StatoTrascodificaStatoTrascodifica
0uploaded5importer_success
1tovalidate6importer_error
2validate_success7approved
3validate_error8not_approved
4toimporter

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.

Ultimo Aggiornamento

13 Dicembre 2023, 16:36