Std004: Standard per lo sviluppo dell interoperabilità applicativa

Transcript

1 1 di 14 DOCUMENTAZIONE UTILIZZO API Comune di Milano Le API che il Comune di Milano mette a disposizione, sono pubblicate sull API STORE all indirizzo Per poterle utilizzare è necessario completare le seguenti fasi: Registrazione di un nuovo utente Creazione di un contenitore delle API (My Application) Sottoscrizione dell API da utilizzare Utilizzo delle chiavi generate Registrazione nuovo utente Il primo passo, per chi vuole utilizzare le API, è quello di registrarsi come utente; nel caso si abbia a disposizione un utenza interna del comune di Milano è possibile utilizzare quella; sarà necessario mandare una mail a Siad.UffInteroperabilità@comune.milano.it, chiedendo di essere inserito con quell utenza nell API STORE. Sia a fronte di un nuovo utente esterno, sia a fronte di richiesta di accesso con credenziali interne, ogni richiesta di utilizzo delle API sarà soggetta a validazione da parte del Technical Management Board (TMB) di Interoperabilità che si metterà in contatto con il richiedente per verificarne i motivi e per mettere in contatto il richiedente con il possessore del dato per eventuali autorizzazioni.

2 2 di 14 Per la registrazione come utente esterno, cliccare sul tasto Sign-up Compilare poi il form con i dati richiesti, scegliendo una username, una password ed indicando un indirizzo corretto.

3 3 di 14 Dopo aver premuto il tasto SUBMIT, comparirà un messaggio che l utente è in attesa di autorizzazione da parte del TMB di Interoperabilità. Il TMB di Interoperabilità contatterà il richiedente per esaminare i motivi della richiesta e successivamente lo avviserà via mail dell esito. Creazione di un contenitore delle API (My Application) Quando l utente è stato abilitato, bisogna accedere all API STORE effettuando la Login e inserire utente e password scelte in fase di registrazione (o quelle dell utente di rete interna del Comune di Milano)

4 4 di 14 Apparirà la pagina iniziale dove saranno presenti tutte le API che si possono sottoscrivere con quell utenza; ogni utenza viene assegnata ad un gruppo che può vedere certe API Cliccando su un API (a sinistra oppure sull icona al centro) si accede alle informazione relative a quell API; prima ancora di sottoscriverla per poterla utilizzare si può scaricare il wsdl, la documentazione e l url per accedervi

5 5 di 14 Per poter sottoscrivere un API è necessario creare un applicazione virtuale che sarà un contenitore di una o più API che faranno parte di un progetto; per esempio si potrebbe creare una applicazione ControlloPermessiAuto che potrebbe comprendere l API dell acceso ai dati anagrafici, l API dell accesso ai dati della motorizzazione, l API della toponomastica, ecc.) Per creare una nuova applicazione bisogna cliccare sulla casella a discesa Applications e selezionare New Application Apparirà una schermata dove si dovrà inserire il nome dell applicazione che si vuole creare ed una breve descrizione, lasciando vuoti gli altri campi

6 6 di 14 Al termine, cliccando sul tasto ADD si inoltrerà al TMB di Interoperabilità, la richiesta di autorizzazione per la creazione di una MyApplication; fino a quando l applicazione non sarà autorizzata, comparirà nell elenco come INACTIVE Anche in questo caso, arriverà la risposta via mail. Sottoscrizione dell API da utilizzare Una volta ottenuta l autorizzazione per la creazione della MyApplication, questa sarà disponibile nell elenco della casella a discesa Applications

7 7 di 14 A questo punto la si può selezionare e procedere quindi con la sottoscrizione dell API che farà parte di quella MyApplication, premento il bottone SUBSCRIBE Anche la sottoscrizione di un API, ultimo passo prima della sua utilizzazione, è soggetta ad approvazione da parte del TMB di Interoperabilità, che avviserà via mail l esito dell operazione

8 8 di 14 Prima che la sottoscrizione venga approvata, andando in MySubscriptions si vedrà l icona dell API in grigio

9 9 di 14 Una volta autorizzata la sottoscrizione, l API sottoscritto apparirà colorato e sarà possibile generare le chiavi della Production e della Sandbox (test) cliccando il bottone GENERATE Utilizzo delle chiavi generate Cliccando su GENERATE verranno generate due tipologie di chiavi: Access Token Consumer Key e Consumer Secret

10 10 di 14 L Access Token viene generato a livello di applicazione ed è valido per tutte le API associate a un'applicazione. Questo permette di accedere a più API con un unico token. Il sistema di autenticazione è OAuth2. La validità di un Access Token è di default impostata a 3600 secondi, dopo i quali il token scade; quando un token scade, gli utenti possono aggiornare il token cliccando sul pulsante Re-generate. Impostare un valore negativo per assicurarsi che il token non scada.

11 11 di 14 La Consumer Key e la Consumer Secret sono necessarie per permettere di invocare una API anche da un'applicazione di terze parti come un app mobile. Per generare un token con la Consumer Key e la Secret Key, bisogna effettuare una chiamata al servizio REST è presente un client REST anche sull API STORE La procedura è la seguente: 1. Comporre una stringa utilizzando la Consumer Key e la Consumer Secret nel formato consumer-key:consumer-secret e codificarla usando base64 ( 2. Accedere al client REST dell API STORE invocando il servizio in modalità POST, inserendo nel campo Headers il valore Authorization: Basic <stringa codificata in base64>, nel

12 12 di 14 campo Payload il valore grant_type=client_credentials e nel campo Content-type il valore application/x-www-form-urlencoded Cliccando SEND si otterrà l access token per poter accedere al servizio. L access token ottenuto in questo modo o direttamente generato nell API STORE va inserito nell header della richiesta soap nel formato Authorization Bearer: <access token>.

13 13 di 14 Ecco un esempio di utilizzo della Consumer-key e della Consumer secret in un applicazione, per farsi restituire un access token valido. Esempio in java: <context-param> <param-name>loginurl</param-name> <param-value> </context-param> <context-param> <param-name>consumerkey</param-name> <param-value>szshscdylekucwa1ghparqlflusa</param-value> </context-param> <context-param> <param-name>consumersecret</param-name> <param-value>wjefrde3jefngmuwvnsenzsxm1sa</param-value> </context-param> classe java per recuperare il token : public Token gettoken { String submiturl = PizzaShackWebConfiguration.getInstance().getLoginURL(); String consumerkey = PizzaShackWebConfiguration.getInstance().getConsumerKey(); String consumersecret = PizzaShackWebConfiguration.getInstance().getConsumerSecret(); try { String applicationtoken = consumerkey + ":" + consumersecret; BASE64Encoder base64encoder = new BASE64Encoder(); applicationtoken = "Basic " + base64encoder.encode(applicationtoken.getbytes()).trim(); String payload = "grant_type=client_credentials"; HttpResponse httpresponse = httpclient.dopost(submiturl,applicationtoken, payload,"application/x-www-form-urlencoded"); if (httpresponse.getstatusline().getstatuscode()!= 200) { return null; } String response = httpclient.getresponsepayload(httpresponse); return JSONClient.getAccessToken(response); } catch (IOException e) {

14 14 di 14 e.printstacktrace(); return null; } Praticamente chiamando l url e passando i parametri consumerkey e consumersecret e come grant_type client_credentials si ottiene l access token di autenticazione con il quale si chiamano i servizi tramite Authorization Bearer e il token recuperato. API usa il framework di autenticazione OAuth2. In.NET si può o utilizzare un client/libreria OAuth2 oppure seguendo l esempio java andare a recuperare il token per poi chiamare il servizio.