Funzioni Avanzate
API REST specifiche per le operazioni di download, clipping e geoprocessing, per garantire l’interoperabilità dei dati
Per garantire l’interoperabilità della piattaforma, sono state implementate delle API basate sul paradigma REST.
Le funzioni possono essere invocate tramite chiamate HTTPS di tipo GET o POST e i dati verranno rilasciati in vari formati che seguono standard approvati da OGC.
Per utilizzare le API è possibile impiegare software quali cURL o Postman, oppure implementare le chiamate ai servizi del DO all’interno del proprio framework di sviluppo (C, Java, Python, ecc.).
INFO GENERALI
Creazione account
Per poter accedere al servizi di scarico ed elaborazione tramite chiamate API o utilizzo dei software (cURL, Postman, ecc.) è necessario registrarsi inviando una mail a info@droughtcentral.it
Per richiedere le credenziali indicare:
- nome
- cognome
- ente o azienda di appartenenza
- fini dell’utilizzo dei dati
Prodotti disponibili
Le funzioni messe a disposizione lavorano su dataset, sia originali che derivati, archiviati nel database del Drought Central. I prodotti utilizzabili con le API e il relativo tag da utilizzare nelle chiamate sono:
ACCESSO AI DATI FACILITATO
Per facilitare l’accesso e l’utilizzo dei dati è stato predisposto un template per Postman (File di configurazione) con tutti i servizi disponibili. Per il suo utilizzo è necessario scaricare il software Postman e importare il file di configurazione:
File di configurazione
COMING SOON
Autenticazione
Al primo accesso, l’utente deve configurare correttamente le variabili di autenticazione nella struttura Postman inserendo le credenziali (e-mail e password) nella sezione “Variables” del template, come da Documentazione scaricabile.
ACCESSO AI DATI TRAMITE USO DIRETTO DELLE API
"Access token" e "Refresh token"
L’accesso alle API è protetto tramite autenticazione basata su token. Tutte le chiamate devono essere effettuate passando nell’header un Access token. L’utilizzo dell’Access token ha una validità di 10 minuti, al termine dei quali dovrà essere riaggiornato tramite il Refresh token.
La prima volta che si vuole effettuare la chiamata o nel caso in cui il refresh token sia scaduto, occorre invocare il servizio di autenticazione (endpoint user), come riportato di seguito.
Generazione di Access token e Refresh token
Tipo di chiamata: POST
url : https://dows.ibe.cnr.it:8443/dows-2-0/api/authentication/user
Funzione per generare un Access token e un Refresh token validi per l’utenza attiva:
- Username: mail dell’utente
- Pssword: password
I parametri si passano all’interno del body come entity (FORM URLENCODED). Questa funzione genererà un nuovo Access token e un nuovo Refresh token.
In caso di riconoscimento avvenuto correttamente verranno rilasciati i 2 token secondo il formato JWT, nel seguente oggetto JSON:
{“access_token”:”TOKEN CODE”, “refresh_token”:”TOKEN CODE”}
Il nuovo Access token avrà una validità di 10 minuti, al termine dei quali dovrà essere rigenerato con una chiamata di refresh (endpoint refresh). Il Refresh token ha una validità di 20 giorni, al termine del quale scadrà la sessione e sarà necessario richiamare il servizio user per rigenerare entrambi i token.
Nel caso di un’autenticazione fallita, verrà restituito il messaggio “Unauthorized”.
Esempio di chiamata (cURL) per generare i token:
curl -X POST –data ‘username=nome.cognome@xxx.it‘ –data ‘password=XXXXXX’ -H ‘Content-
Type: application/x-www-form-urlencoded’ https://dows.ibe.cnr.it:8443/dows-2.0/api/authentication/user
Refresh dell'Access token
Tipo di chiamata: POST
url : https://dows.ibe.cnr.it:8443/dows-2-0/api/authentication/refresh
Funzione da chiamare per poter ri-generare l’Access token quando è scaduto. L’utilizzo del servizio di Refresh richiede l’inserimento del Refresh token nel body della richiesta, inoltre l’header della richiesta deve avere:
content-type: text/plain
Il risultato sarà rilasciato in un oggetto json che può coprire i seguenti casi:
1- Il Refresh token è ancora valido quindi è stato generato un nuovo Access token.
{“result”:”refresh”,”access_token”:”NEW TOKEN”}
2- L’Access token non è ancora scaduto, quindi non viene rigenerato ed è restituito nel json.
{“result”:”alive”,”access_token”:”OLD TOKEN”}
3- Entrambi i token sono scaduti, quindi occorre utilizzare il servizio user per rigenerarli.
{“result”:”death”}
Esempio di chiamata (cURL) per fare il refresh dell’Access token:
curl -X POST –data “REFRESH TOKEN” -H “Content-Type: text/plain” https://dows.ibe.cnr.it:8443/dows-2.0/api/authentication/refresh
Utilizzo dell'Access token per effettuare le chiamate
Quando si effettua una chiamata a un qualsiasi servizio del Drought Central l’Access token valido deve essere inserito nell’header della chiamata secondo il seguente schema
Authorization:VALID_ACCESS_TOKEN
Esempio di chiamata (cURL) che restituisce le date disponibili per l’indice SPI1:
curl -X GET ‘https://dows.ibe.cnr.it:8443/dows-2.0/api/info/data/spi1’ -H ‘Authorization: VALID_ACCESS_TOKEN’
Documentazione per l'implementazione dei singoli servizi API disponibili
Nel seguente documento vengono spiegate le modalità di implementazione dei servizi API disponibili.
Documentazione
COMING SOON
