Come creare e rendere disponibile un e-service

In questo tutorial vedremo come creare da zero un e-service PDND. 

Che cos'è un e-service? In PDND Interoperabilità, gli e-service sono delle API che rispettano il perimetro di sicurezza e gli standard del modello di interoperabilità (ModI), e che vengono pubblicate sul catalogo di PDND con il corredo di tutte le informazioni di contesto necessarie al loro utilizzo.

Per creare un e-service occorre quindi, per prima cosa, rendere disponibile una API di un servizio. Una volta pronta l’API, ecco come procedere per pubblicarla sotto forma di e-service.

La prima cosa da fare sarà selezionare la voce erogazione dal menu e quindi “I tuoi e-service”, per poi procedere facendo click sul pulsante +1 Crea nuovo:

In questo modo si atterrerà sulla pagina di creazione dell’e-service.

Vediamo le voci nel dettaglio. I contenuti della prima pagina fanno riferimento a informazioni generali sull’e-service:

• un nome e una descrizione che saranno quelli esposti all'interno del catalogo degli e-service sulla piattaforma PDND Interoperabilità;
• con quale tecnologia è scritta l'API attraverso la quale si intende erogare il servizio, se REST o SOAP;
• se l’e-service è destinato a erogare o ricevere dati;
• se il processo di distribuzione dei segnali di variazione è disponibile per questo e-service, ossia se il fruitore potrà ricevere aggiornamenti se un dato di suo interesse varia nel tempo.

Alcune di queste informazioni, come ad esempio la tecnologia dell’API, non potranno più essere modificate una volta che la prima versione di questo e-service verrà pubblicata.

Gli step 2, 3 e 4 di creazione di un e-service fanno riferimento al contenuto della specifica versione. La prima volta che si crea un e-service, la versione sarà naturalmente la 1. Queste le informazioni richieste:

1. Descrizione della versione: un changelog delle modifiche apportate tra questa versione e la precedente.
2. Durata della validità del voucher: dopo quanto tempo scade il voucher rilasciato da PDND Interoperabilità valido per accedere a questo servizio. Questo valore, espresso in minuti, determina per quanto tempo sarà valido l’access token utilizzabile nello scambio tra voi e il fruitore. Alla scadenza il fruitore dovrà fare richiesta di un nuovo access token a PDND Interoperabilità per poter accedere nuovamente al dato dell'erogatore.
3. Audience: il parametro audience (aud) che i fruitori dovranno inserire all'interno del token per le richieste che effettueranno verso questa versione dell'e-service.
4. Soglie delle chiamate API: qui dovete segnalare quanto carico espresso in numero di chiamate API al giorno dichiarate di poter sostenere per ogni singolo fruitore e in totale, sommando le richieste di tutti i fruitori. Questo meccanismo ha un corrispettivo per il fruitore. Ogni volta che il fruitore crea una nuova finalità per accedere al dato dichiarerà quanto carico intende mettere sulla vostra infrastruttura. Nel momento in cui il valore o la somma dei valori fosse superiore a quello che voi erogatori avete dichiarato di poter supportare, la nuova finalità non sarà attivata immediatamente, ma rimarrà in attesa di approvazione.
5. Modalità di attivazione delle richieste di fruizione: potete decidere se, qualora il fruitore avesse già tutti gli attributi richiesti, all’atto dell’invio della richiesta di fruizione, questa possa essere attivata manualmente dalla piattaforma, senza richiedere un’azione manuale da parte di un operatore dell’erogatore.

Gli attributi sono di fatto delle proprietà che noi erogatori dell'e-service pretendiamo che i fruitori posseggano per potersi iscrivere a fruire dell’e-service. Sono divisi in tre tipologie: certificati, verificati e dichiarati.

Gli attributi certificati vengono attribuiti automaticamente all’ente in base alle informazioni presenti nei database delle fonti autoritative a disposizione di Interoperabilità. In questo momento, la principale fonte autoritativa è il Catalogo IPA.

Per gli attributi dichiarati, l'ente fruitore, all'atto della sottoscrizione di una richiesta di fruizione, dichiara implicitamente di possederli. La veridicità di questa dichiarazione è a solo carico del fruitore e non necessita di verifica da parte dell'ente erogatore. 

La verifica degli attributi verificati è invece a carico dell’erogatore, sulla base dell’eventuale documentazione che il fruitore presenterà.

Interfaccia API: Se al primo step avete dichiarato un servizio REST dovrete caricare un file OpenAPI; se si tratta di un servizio SOAP, un file WSDL. In entrambi i casi il documento da caricare conterrà la specifica dell'interfaccia che esporrete verso il pubblico. Questo campo è obbligatorio e può essere modificato solo creando una nuova versione di e-service.

Documentazione tecnica: Eventuale documentazione a corredo per la corretta implementazione ed uso dell’API, come ad esempio manuali d’uso.

Un e-service in bozza può essere pubblicato immediatamente al termine della procedura guidata di creazione della versione o in un secondo momento.

Una volta pubblicata una bozza, questa diventerà la nuova versione "attiva" dell'e-service, mandando la versione precedente in stato "deprecato". Le versioni deprecate continueranno a funzionare per garantire ai fruitori continuità di servizio. Ai fruitori sarà indicato che possono aggiornare la loro richiesta di fruizione alla versione più recente dell'e-service.