Introduzione¶

Le Linee Guida individuano le tecnologie e gli standard che le Pubbliche Amministrazioni devono tenere in considerazione durante la realizzazione dei propri sistemi informatici, al fine di permettere il coordinamento informativo e informatico dei dati tra le amministrazioni centrali, regionali e locali, nonché tra queste e i sistemi dell’Unione Europea, con i gestori di servizi pubblici e dei soggetti privati.

Le Linee Guida assicurano l’aggiornamento rispetto alla:

• evoluzione della tecnologia;
• aderenza alle indicazioni europee in materia di interoperabilità;
• adeguatezza alle esigenze delle pubbliche amministrazioni e dei suoi utenti;
• adozione da parte di tutti i soggetti, pubblici e privati;
• adeguatezza dei necessari livelli di sicurezza.

Le Linee Guida contribuiscono alla definizione del Modello di Interoperabilità della PA (in breve ModI), focalizzandosi sulle tecnologie e le loro modalità di utilizzo, per assicurare lo scambio di dati tra le PA, e tra queste e i soggetti privati; in esse sono definiti i contesti di interazione e integrazione tra le PA, i cittadini e le imprese.

La definizione del ModI è coerente con il nuovo European Interoperability Framework (in breve EIF) oggetto della Comunicazione COM (2017) 134 della Commissione Europea del 23 marzo 2017 [1], al fine di assicurare l’interoperabilità nel contesto Europeo e per l’attuazione del Digital Single Market (Mercato Unico Digitale).

Nell’ottobre 2005 il CNIPA (oggi Agenzia per l’Italia digitale - AgID) ha pubblicato un insieme di documenti che costituivano il riferimento tecnico per l’interoperabilità fra le PA. Tali documenti delineavano il quadro tecnico-implementativo del Sistema pubblico di cooperazione (SPCoop), il framework di interoperabilità a livello applicativo adottato dalle PA.

Le Linee Guida, e più in generale il ModI, completano il processo di aggiornamento del SPCoop avviato con la determinazione AgID 219/2017 - «Linee guida per transitare al nuovo modello di interoperabilità» [2].

Le Linee Guida considerano i soli servizi digitali (di seguito e-service) realizzati da una Pubblica Amministrazione per assicurare l’accesso ai propri dati e/o l’integrazione dei propri processi attraverso l’interazione dei suoi sistemi informatici con quelli dei fruitori.

Le Linee Guida contribuiscono alla definizione del Modello di Interoperabilità della PA (in breve ModI) relativamente agli e-service provvedendo a:

• definire le modalità di integrazione tra le PA, e tra queste, cittadini e imprese, armonizzando le scelte architetturali di interoperabilità delle PA;
• individuare le scelte tecnologiche che favoriscano lo sviluppo, da parte delle PA, cittadini e imprese, di soluzioni applicative innovative che semplifichino e abilitino l’utilizzo dei dati e dei servizi digitali;
• promuovere l’adozione dell’approccio «API first» per favorire la separazione dei livelli di backend e frontend, con logiche aperte e standard pubblici che garantiscano ad altri attori, pubblici e privati, accessibilità e massima interoperabilità di dati e servizi digitali;
• privilegiare standard tecnologici, de iure e de facto, che soddisfino l’esigenza di rendere sicure le interazioni tra le PA, e tra queste, cittadini e imprese;
• favorire l’interazione tra PA, e tra queste, cittadini e imprese, attraverso un approccio Contract-First.

Il ModI è coerente con European Interoperability Framework (EIF) che fornisce orientamenti alle PA Europee su come operare le iniziative relative al tema dell’interoperabilità attraverso una serie di raccomandazioni atte a stabilire relazioni tra le varie organizzazioni, razionalizzare i processi volti a sostenere i servizi digitali e assicurare che le norme esistenti e quelle nuove non pregiudichino gli sforzi di interoperabilità [3].

Le Linee Guida affrontano il livello di interoperabilità tecnica prevista nell’EIF [4] relativamente agli Interoperable Digital Public Services.

Il ModI assicura l’adozione degli standard di interoperabilità mandatori individuati dalla Comunità Europea (ad esempio INfrastructure for SPatial InfoRmation in Europe [5]) e sostiene le iniziative di standardizzazione promosse dalla Commissione Europea (ad esempio Solution Architecture Template for e-Procurement [6], Solution Architecture Template for Open Data [7]).

Ambito di applicazione¶

Le Linee Guida sull’interoperabilità tecnica delle Pubbliche Amministrazioni sono redatte in ottemperanza:

• alla lettera a comma 2 dell’articolo 14-bis del decreto legislativo 7 marzo 2005, n. 82 (Codice dell’Amministrazione Digitale), che individua le funzioni dell’Agenzia per l’Italia Digitale (AgID) tra cui: «emanazione di Linee […] di indirizzo […] sull’attuazione e sul rispetto delle norme di cui al presente Codice, anche attraverso l’adozione di atti amministrativi generali, in materia di […] interoperabilità e cooperazione applicativa tra sistemi informatici pubblici e quelli dell’Unione europea»;
• alla lettera b comma 3-ter dell’articolo 73 del decreto legislativo 7 marzo 2005, n. 82 (Codice dell’Amministrazione Digitale), in cui è indicato che il Sistema pubblico di connettività è costituito da «linee guida e regole per la cooperazione e l’interoperabilità».

Le Linee Guida sono emanata ai sensi dell’articolo 71 del decreto legislativo 7 marzo 2005, n. 82 (Codice dell’Amministrazione Digitale).

Riferimenti e sigle¶

Principi generali¶

Progettazione dei servizi digitali e degli e-service¶

Nella realizzazione delle proprie funzioni istituzionali le Pubbliche Amministrazioni implementano procedimenti amministrativi, definendo processi con l’obiettivo di realizzare servizi ai cittadini e imprese efficienti ed efficaci.

Un servizio consiste in un’attività o in una serie di attività svolte in uno scambio tra un fornitore e un cliente.

Il CAD all’art.64-bis comma 1-bis prevede che le PA, i fornitori di identità digitali e i prestatori dei servizi fiduciari qualificati, «in sede di evoluzione, progettano e sviluppano i propri sistemi e servizi in modo da garantire l’integrazione e l’interoperabilità tra i diversi sistemi e servizi (..) espongono per ogni servizio le relative interfacce applicative» (API). Lo stesso art.64-bis al comma 1-quater prevede che le PA «rendono fruibili tutti i loro servizi anche in modalità digitale».

Se l’efficacia di un servizio pubblico è determinata dal soddisfacimento della norma, l’efficienza può essere incrementata utilizzando gli strumenti propri della Information and Communication Technology (ICT) in coerenza col principio «digital first».

I processi che utilizzano gli strumenti ICT sono qui detti processi digitali.

Un e-service è un servizio erogato via Internet o attraverso una rete privata tramite un processo digitale in cui sono coinvolti erogatori e fruitori. Gli e-service sono una particolare categoria di servizi in rete basati su interfacce applicative (API).

Gli e-service di interesse delle Linee Guida sono caratterizzati da:

• il descrittore dell’e-service, un’entità che descrive l’obiettivo e le modalità per usufruire del servizio;
• le API che comprendono le modalità di accesso ad un e-service, le cui implementazioni tecnologiche si basano sulla combinazione dei pattern di interoperabilità e sicurezza o l’utilizzo di profili di interoperabilità;
• gli accordi di interoperabilità in cui sono definiti i legami tra fruitore ed erogatore.

Si assume che le Pubbliche Amministrazioni siano viste come un’entità unica da cittadini e imprese, e che, coordinandosi e collaborando, forniscano servizi.

Ne consegue che la realizzazione di un processo digitale necessita di un modello organizzativo che individui ruoli e responsabilità dei soggetti coinvolti. Nel caso in cui il servizio offerto necessiti di interazioni tra diverse Pubbliche Amministrazioni il modello organizzativo deve essere condiviso dalle stesse.

Il processo digitale determina l’insieme di e-service:

• necessari ad assicurare l’interazione tra le Pubbliche Amministrazioni (e-service di backend);
• finalizzati ad assicurare l’offerta di e-service a cittadini e imprese (e-service di frontend).

La conoscenza della disponibilità e le modalità di utilizzo degli e-service di backend e dei servizi di front-end, utilizzati direttamente da sistemi informatici, è assicurata dalla pubblicazione sul Catalogo delle API previsto nel ModI.

Tali azioni sono realizzate direttamente dagli erogatori di e-service o da un ente capofila.

Figura 2 - (A) Processo Digitale Semplice. (B) Processo Digitale Collettivo

Nell’ambito del ModI, con processi digitali semplici si intendono i processi digitali che vedono coinvolta un singolo erogatore verso i cittadini e le imprese. Viceversa, con processi digitali collettivi si indicano i processi digitali che vedono coinvolte più organizzazioni.

Di seguito sono descritte delle buone pratiche per:

• supportare l’interoperabilità dei sistemi informatici;
• favorire il riutilizzo degli e-service.

Per dare seguito alla trasformazione digitale della Pubblica Amministrazione, nel ModI, la definizione dei processi digitali deve assicurare il rispetto dei principi del digital-by-default [1] e once-only [2].

La definizione di un processo digitale è avviata da una Pubblica Amministrazione ed è composta dalle fasi indicati di seguito.

1) Individuazione delle esigenze.

Fase in cui vengono determinate le esigenze, attraverso cui l’erogatore:

1. analizza la norma per determinare le funzioni di competenza e gli obiettivi da raggiungere. Sulla base di questi, evidenzia le caratteristiche del servizio da offrire, e individua i dati in ingresso e quelli restituiti.
2. determina se coinvolgere altre organizzazioni quali fonti autoritative dei dati necessari o soggetti preposti all’esecuzione di endoprocedimenti specifici.
3. determinare le attività necessarie ad implementare ed assicurare l’implementazione del servizio da offrire.

2) Organizzativa.

Fase in cui l’erogatore in base al punto 1.b coinvolge o meno altre organizzazioni:

• se non sono state individuate altre organizzazioni:
  1. l’erogatore realizza un processo digitale semplice in cui valuta la possibilità soddisfare le esigenze riusando e/o reingegnerizzando uno o più e-service già erogati, altrimenti implementa nuovi e-service progettandoli in modo da favorirne il riuso.
• se sono state individuate altre organizzazioni si realizza un processo digitale collettivo dove:
  1. l’erogatore individua le organizzazioni da coinvolgere in quanto fonti autoritative dei dati o soggetti preposti all’esecuzione di endoprocedimenti, evitando la duplicazione non necessaria dei dati;
  2. l’erogatore si confronta con esse per determinare ruoli e responsabilità;
  3. ogni organizzazione, per dare seguito alle responsabilità individuate valuta la possibilità soddisfare le esigenze riusando e/o reingegnerizzando uno o più e-service già erogati, altrimenti implementa nuovi e-service progettandoli in modo da favorirne il riuso.

3) Semantica.

Fase in cui le organizzazioni interessate, definiscono il modello dati da utilizzare (entità, proprietà e relativa metadatazione).

La definizione del modello dati è realizzata in coerenza con i vocabolari controllati e modelli di dati definiti a livello nazionale e internazionale.

4) Tecnica.

Fase in cui le organizzazioni interessate provvedono, ove necessario, a garantire la conformità al modello dati da utilizzare degli e-service individuati in fase di individuazione e/o implementazione delle API, per assicurare la disponibilità degli e-service.

5) Governance dei servizi.

Fase in cui ciascuna erogatore pubblica sul Catalogo le API implementate, in modo da incentivare l’utilizzo ed il riuso.

Stipula degli accordi di interoperabilità, dove sono formalizzati ruoli e responsabilità delle parti (erogatore e fruitore), per assicurare che le Pubbliche Amministrazioni interessate possano usufruire di un e-service fornito da un’altra PA attraverso una o più API.

Si rimanda ai seguenti paragrafi per dettagli.

Tecnologie per le API¶

Un aspetto che si vuole qui richiamare è la relazione tra l’interno e l’esterno del sistema informativo di una Pubblica Amministrazione, e come questo confine abbia impatti sugli e-service in termini di funzionalità e sicurezza.

Nel precedente modello di interoperabilità (il cosiddetto SPCoop del 2005) era stato definito il concetto di dominio di un’amministrazione, a indicare l’insieme delle risorse (dati e servizi) e delle politiche che un’amministrazione assicurava per dare seguito alla cooperazione con altre. Il confine tra i domini delle amministrazioni era istanziato fisicamente da uno specifico elemento architetturale, la Porta di Dominio (PdD).

Nel nuovo framework di interoperabilità, l’istanziazione della PdD come punto unico di accesso a un’interfaccia viene meno. Tuttavia, concettualmente il confine del dominio dell’amministrazione continua a esistere ed è importante considerarlo nella progettazione degli e-service. Gli e-service sono offerti da qualsiasi server applicativo, senza essere vincolati a essere raggiungibili attraverso un unico gateway.

Quindi, ogni server applicativo offre e-service, tuttavia è comunque significativo distinguere se gli stessi sono offerti per interoperare:

1. all’interno del dominio (da parte di client applicativi offerti dalla stessa amministrazione (ad es., un’applicazione Web o una mobile verso il back-end, integrazione tra banche dati nel back-end, ecc);
2. verso altre amministrazioni o altri soggetti con cui è stabilita una relazione di fiducia.

Le Pubbliche Amministrazioni, nella loro autonomia organizzativa possono adottare queste Linee Guida anche per i servizi sviluppati all’interno del proprio dominio. Adottare il principio API-first per i servizi interni permette di riutilizzare le componenti e di integrarle più facilmente con quelle delle altre organizzazioni in caso di necessità. Le regole tecniche inoltre permettono di applicare criteri di qualità uniformi per tutti i servizi ICT, consolidando le prassi di sicurezza, migliorando la qualità della spesa e mitigando i rischi anche interni legati alla protezione dei dati personali.

Una trattazione completa dei paradigmi per la progettazione e realizzazione delle API esula dagli scopi del presente documento. La breve discussione che viene presentata in questa sezione vuole ricordare a chi legge le differenti tecnologie per la realizzazione di API e il modello architetturale sottostante (RPC-like o resource-oriented).

Le API possono essere progettate secondo due paradigmi:

Remote Procedure Call (RPC)-like.

In questo paradigma, un’interfaccia di servizio espone una serie di operazioni (metodi) che permettono l’invocazione delle operazioni offerte dall’interfaccia. Il significato dell’operazione è informalmente espresso dal nome dell’operazione, dal numero e dal tipo dei suoi parametri, dal tipo del valore di ritorno (il tutto viene detto tecnicamente firma o signature). Approcci formali prevedono che tale significato venga eventualmente anche descritto in opportuni documenti di accompagnamento e/o attraverso specifiche formali dell’interfaccia di servizio. Ogni operazione può quindi rappresentare, sia semplici operazioni di computazione, sia operazioni potenzialmente di lunga durata, sia operazioni di accesso a dati, ecc. Il paradigma è detto RPC-like in quanto le API ricordano le librerie di chiamata a procedura e quindi l’interfaccia, metaforicamente, è di fatto una libreria di funzioni.

Resource-oriented.

In questo paradigma, l’interfaccia di servizio offre operazioni di creazione, lettura, aggiornamento e cancellazione di risorse. In inglese, Create, Read, Update, Delete, da cui l’acronimo da cui prende il nome il paradigma: CRUD. Una risorsa è un qualsiasi oggetto informativo che possiede uno stato. In questo paradigma, l’interfaccia di servizio è metaforicamente un accesso diretto a una base informativa, e le uniche operazioni possibili sono appunto le modifiche a tali risorse.

Parallelamente, esistono delle tecnologie con cui poter naturalmente realizzare API, che sono:

1. SOAP e il cosiddetto stack WS-*
2. lo stile architetturale REST, basato su HTTP.

Un Web service SOAP

espone un insieme di metodi richiamabili da remoto da parte di un client. SOAP definisce una struttura dati per lo scambio di messaggi tra applicazioni, codificata in XML; di fatto SOAP utilizza HTTP come protocollo di trasporto, ma non è limitato né vincolato ad esso.

Un Web service che sfrutta l’architettura REST

adotta il modello basato su risorse secondo le seguenti caratteristiche:

• individuazione delle risorse mediante il formalismo dei Uniform Resource Identifier (URI);
• operazioni sulle risorse effettuate sulla rappresentazione del loro stato;
• CRUD sulle risorse mediante HTTP utilizzando i metodi nella semantica prevista dal protocollo stesso.

L’approccio REST evidenzia le caratteristiche del Web come piattaforma leggera per l’elaborazione distribuita. Non è in prima istanza necessario aggiungere nulla a quanto è già esistente sul Web per consentire ad applicazioni remote di interagire.

Si noti che nell’applicazione pratica di REST si assiste al suo uso in modalità non del tutto canoniche. Ogni deviazione rispetto alle caratteristiche previste da REST porta alla realizzazione di architetture ibride tra il paradigma RESTful Web service e quello dei Web service RPC-like. In merito ai modelli ibridi che si possono presentare, esiste una classificazione, il cosiddetto Richardson Maturity Model 3 che prevede quattro livelli, da 0 a 3, in accordo al grado di aderenza ai dettami REST. In particolare, si possono presentare i casi seguenti:

Livello 0

per servizi che semplicemente usano HTTP come protocollo di trasporto applicativo (tunnel HTTP). In questo caso il sistema non ha niente del modello REST.

Livello 1

per i servizi che operano sulle risorse definite secondo la sintassi e la semantica previste per le URI, sulle quali si opera invocando delle operazioni (metodi) che agiscono su di esse.

Livello 2

per i servizi che operano su risorse definite secondo la sintassi e la semantica previste per le URI, sulle quali si opera sulla rappresentazione del loro stato per mezzo del protocollo HTTP usando la semantica dei metodi (verbi) come previsti dal protocollo.

Livello 3

come per il livello 2, con in aggiunta la possibile presenza di controlli ipermediali nella rappresentazione delle risorse.

Le Linee Guida accolgono l’implementazione di API REST classificabili al livello 1 del Richardson Maturity Model.

Le Linee Guida accolgono indifferentemente SOAP e REST quali tecnologie per l’implementazione delle API. La scelta della tecnologia da utilizzare è lasciata alle Pubbliche Amministrazioni che costituiscono un dominio di interoperabilità sulla base delle specifiche esigenze.

Pattern e profili di interoperabilità¶

Le diverse esigenze di interoperabilità delle PA e l’esperienza da loro maturata hanno evidenziano l’impossibilità di adottare un unico approccio risolutivo. Di contro, esigenze simili tra i vari domini determinano l’opportunità di definire un insieme di soluzioni tecnologiche comuni che permettano, anche attraverso la loro combinazione, di definire un quadro condiviso di regole applicate.

Le Linee Guida individuano i pattern e i profili di interoperabilità come modalità tecniche condivise secondo le quali un fruitore e un erogatore realizzano l’interoperabilità dei propri sistemi informatici, Nel dettaglio:

• i pattern di interoperabilità risolvono singoli requisiti che la PA deve soddisfare, e si dividono in:
  • pattern di interazione che descrivono il modello di comunicazione tra fruitore ed erogatore;
  • pattern di sicurezza che descrivono le modalità per assicurare specifiche caratteristiche di sicurezza della comunicazione;
• i profili di interoperabilità sono combinazioni dei pattern di interoperabilità per risolvere i casi d’uso che una PA deve soddisfare.

I pattern e i profili di interoperabilità che le PA DOVREBBERO utilizzare sono indicati nei Documenti Operativi: Pattern di integrazione, Pattern di sicurezza e Profili di interoperabilità.

Nel caso in cui le Pubbliche Amministrazioni rilevino l’impossibilità di dare seguito alle specifiche esigenze dei domini di interoperabilità che le vedano coinvolte, a causa della mancanza di pattern e/o profili di interoperabilità adeguati, o evidenzino l’opportunità di aggiornare i pattern e i profili di interoperabilità esistenti, DEVONO segnalare la circostanza ad AgID, definendo un esigenza e/o formulando una proposta.

L’AgID, stimolata dalle esigenze e dalle proposte della PA o su propria iniziativa, avvia un tavolo pubblico di concertazione per modificare o definire nuovi e/o modificare i pattern e/o i profili di interoperabilità.

I nuovi pattern e/o i profili di interoperabilità o la modifica di quelli esistenti sono formalmente introdotti nel ModI attraverso Circolari emanate dall’AgID per l’aggiornamento dei Documenti Operativi: Pattern di integrazione, Pattern di sicurezza e Profili di interoperabilità.

Il processo di mantenimento dei pattern prevede le seguenti fasi:

1. [NUOVA ESIGENZA E PROPOSTA] Le PA o AgID individuano nuove esigenze di interoperabilità e POSSONO proporre nuovi pattern come soluzione;

2. [CONCERTAZIONE] AgID apre il tavolo pubblico, in modo da acquisire eventuali proposte alternative per soddisfare le nuove esigenze evidenziate;

3. [ADOZIONE] AgID, valutando le proposte pervenute, individua i nuovi pattern che rispondono alle esigenze e aggiorna i Documenti Operativi.

Il processo di mantenimento dei pattern è realizzato da cicli successivi di applicazione delle fasi individuate. La pianificazione dei cicli di proposta assicura la raccolte delle esigenze dal 1 gennaio al 31 dicembre di ogni anno.

• (i)° ciclo [1 gennaio anno corrente - 31 ottobre anno corrente ]
  1. [NUOVA ESIGENZA E PROPOSTA] da 1° gennaio anno corrente - 30 giugno anno corrente
  2. [CONCERTAZIONE] dal 1 maggio anno corrente - 31 agosto anno corrente
  3. [ADOZIONE] dal 1° settembre anno corrente - 31 ottobre anno corrente
• (i+1)° ciclo [1 luglio anno corrente - 30 aprile anno successivo]
  1. [NUOVA ESIGENZA E PROPOSTA] da 1° luglio anno corrente - 31 dicembre anno corrente
  2. [CONCERTAZIONE] dal 1 novembre anno corrente - 31 febbraio anno successivo
  3. [ADOZIONE] dal 1° marzo anno successivo - 30 aprile anno successivo

Figura 4 - Rappresentazione del processo di gestione dei pattern

Si rimanda ai seguenti paragragi per dettagli.

Governance dei servizi¶

Il ModI identifica negli e-service gli elementi atomici per dare seguito allo scambio di dati e informazioni tra le Pubbliche Amministrazioni, le imprese e i cittadini.

Nel ModI, il Catalogo delle API è la componente che gestisce il ciclo di vita della pubblicazione, consultazione e fruizione degli e-service, assicurando la specifica delle API che essi implementano.

Il Catalogo delle API implementa quanto previsto dal CAD all’art.73, comma 3-ter, lettera c).

Gli e-service registrati nel Catalogo, per normalizzare l’integrazione tra i sistemi informatici, utilizzano le tecnologie, i pattern e i profili individuati nelle Linee Guida.

Relativamente a un’e-service, indichiamo con:

• erogatore la PA che lo rende disponibile;
• fruitore i soggetti (PA, imprese e cittadini) che lo utilizzano;
• ente capofila le PA responsabili, su delega di altre PA, delle attività di gestione sul Catalogo.

Il Catalogo realizza un punto centrale, unico per la pubblicazione, di consultazione e fruizione degli e-service, permettendo:

• alle PA erogatrici o alle PA ente capofila di pubblicare e gestire gli e-service;
• ai soggetti fruitori (PA, imprese e cittadini) di consultare gli e-service disponibili;
• alle PA erogatrici e ai soggetti fruitori di registrare, ove necessario, gli elementi tecnici convenuti per utilizzare gli e-service.

Nell’ambito di relazioni tra differenti soggetti (erogatori e fruitori) determinata dall’utilizzo di e-service è necessario concordare l’efficienza di questi ultimi. La misura dell’efficienza avviene attraverso l’individuazione dei seguenti elementi:

• Service-Level Indicator (di seguito SLI), ovvero metriche atte a misurare l’efficienza dei servizi individuati dall’erogatore;
• Service-Level Objective (di seguito SLO), ovvero gli obiettivi degli SLI per i servizi definiti dall’erogatore;
• Service-Level Agreement (di seguito SLA), ovvero accordi sul livello di servizio frutto della contrattazione tra erogatore e fruitore.

Un e-service è rappresentato nel Catalogo dalle seguenti entità:

• i descrittori dell’e-service, che definiscono le informazioni relative alla natura dell’e-service e DEVONO essere pubblicati dalle PA erogatrici.
• le API, che definiscono le modalità tecniche per usufruire dell’e-service e DEVONO essere pubblicate e gestite dalle PA erogatrici.
• gli accordi di interoperabilità, che permettono alle PA erogatrici e ai fruitori di dichiarare la costituzione di una relazione di utilizzo, comprensiva degli SLA condivisi quali insieme delle responsabilità e degli obblighi nell’utilizzo delle API, e DEVONO essere confermati dalla PA erogatrici e dai fruitori.

Figura 5 - Entità gestite dal Catalogo

Si precisa che gli erogatori, nell’ambito della definizione dei un’e-service, individuano le API da loro implementate e, allo stesso tempo, le API che i fruitori devono utilizzare per usufruire dell’e-service.

Il Catalogo supporta una governance distribuita degli e-service, assicurando i seguenti obiettivi:

• favorire l’uso degli e-service attraverso la loro pubblicazione;
• agevolare l’accentramento della gestione del ciclo di vita delle API;
• mitigare la creazione di API ridondanti;
• regolamentare le relazioni tra erogatore e fruitore, ove necessario, dichiarando i relativi SLA.

Il Catalogo, unico e centralizzato, è reso disponibile alle PA, alle imprese e ai cittadini dalla piattaforma realizzata da AgID a tale scopo.

Introduzione¶

Il pattern di interazione definisce le modalità secondo le quali un fruitore ed un erogatore possono interagire. L’interazione avviene definendo le API.

I pattern di interazione quali riferimenti concettuali coniugano, fatto salvo per l’accesso CRUD, i message exchange pattern (MEP) per le tecnologie SOAP e REST proposte dal ModI.

Di seguito l’attenzione è rivolta agli aspetti funzionali rimandando per gli aspetti di sicurezza all’apposito Documento Operativo - Pattern di sicurezza.

Il Documento operativo descrive i pattern di interazione individuati da AgID che gli erogatori DEVONO utilizzare per soddisfare le necessità individuate dai requisiti funzionali e non funzionali delle specifiche interazioni con i propri fruitori.

Data la variabilità nel tempo delle esigenze delle amministrazioni e delle tecnologie abilitanti, nonché considerata la natura incrementale del ModI, l’elenco dei pattern di interazione non è da intendersi esaustivo. Nel caso in cui un’amministrazione abbia esigenze non ricoperte nei seguenti pattern di interazione DEVE informare l’Agenzia per l’Italia Digitale, nei modi indicati nel capitolo 7 «Pattern e profili di interoperabilità delle Linee Guida sull’interoperabilità tecnica delle Pubbliche Amministrazioni».

Ambito di applicazione¶

Il presente Documento operativo, allegato delle Linee Guida sull’interoperabilità tecnica delle Pubbliche Amministrazioni, riporta i pattern di interazione definiti nel ModI.

Riferimenti e sigle¶

Principi generali¶

Pattern bloccanti¶

Lo sviluppo di una interfaccia bloccante di tipo RPC-like si richiede nei casi in cui:

• L’esecuzione del metodo è poco onerosa computazionalmente e può essere portata immediatamente a termine dall’erogatore.
• Il contesto rende complessa l’implementazione delle modalità non bloccanti. Ad esempio, non è possibile per il fruitore esporre una propria interfaccia di servizio ed il fruitore non può farsi carico di mantenere il contesto necessario ad effettuare attesa attiva.

Figura 1 - Interazione bloccante RPC

In questo pattern si ha una risposta da parte dell’erogatore contestuale alla richiesta del fruitore. La figura mostra lo schema di questa interazione.

Nel seguito, per gli esempi proposti si fa riferimento ad un’amministrazione denominata ente.example che offre un’interfaccia di servizio secondo le due diverse tecnologie REST o SOAP. Inoltre, per quanto riguarda i pattern relativi a chiamata a procedura remota (bloccante e non bloccante), si farà riferimento ad un metodo M che accetta come parametri:

• a, un oggetto contenente a sua volta un array a1 di interi ed una stringa a2;
• b, una stringa;

e restituisce una stringa c come output.

Le implementazioni degli esempi sono corredate dalla specifica dell’interfaccia e da uno scambio di messaggi esemplificativo.

Di seguito le indicazioni per le tecnologie accolte dal ModI.

L’AgID assicura l’aggiornamento degli stessi per soddisfare le esigenze espresse dalle PA.

openapi: 3.0.1
info:
 title: RESTblocking
 version: "1.0"
 description: |-
   Questo file descrive semplicemente i metodi di un'API
   e non indica tutte le informazioni di metadatazione che
   normalmente vanno inserite.
 license:
   name: Apache 2.0 License
   url: http://www.apache.org/licenses/LICENSE-2.0.html
paths:
 /resources/{id_resource}/M:
   post:
     description: Esegue M
     operationId: M
     parameters:
     - name: id_resource
       in: path
       required: true
       schema:
         type: integer
         format: int32
     requestBody:
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/MType'
     responses:
       200:
         description: Esecuzione di M avvenuta con successo
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/MResponseType'
       400:
         description: Richiesta non valida
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/ErrorMessage'
       404:
         description: Identificativo non trovato
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/ErrorMessage'
       default:
         description: |-
           Errore inatteso. Non ritornare informazioni
           sulla logica interna e/o non pertinenti all'interfaccia.
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/ErrorMessage'

components:
 schemas:
   MType:
     type: object
     properties:
       a:
         $ref: '#/components/schemas/AComplexType'
       b:
         type: string
   MResponseType:
     type: object
     properties:
       c:
         type: string
   AComplexType:
     type: object
     properties:
       a1s:
         type: array
         items:
           type: integer
           format: int32
       a2:
         type: string
   ErrorMessage:
      type: object
      properties:
        detail:
          description: |
            A human readable explanation specific to this occurrence of the
            problem.
          type: string
        instance:
          description: |
            An absolute URI that identifies the specific occurrence of the problem.
            It may or may not yield further information if dereferenced.
          format: uri
          type: string
        status:
          description: |
            The HTTP status code generated by the origin server for this occurrence
            of the problem.
          exclusiveMaximum: true
          format: int32
          maximum: 600
          minimum: 100
          type: integer
        title:
          description: |
            A short, summary of the problem type. Written in english and readable
            for engineers (usually not suited for non technical stakeholders and
            not localized); example: Service Unavailable
          type: string
        type:
          default: about:blank
          description: |
            An absolute URI that identifies the problem type.  When dereferenced,
            it SHOULD provide human-readable documentation for the problem type
            (e.g., using HTML).
          format: uri
          type: string

POST /rest/nome-api/v1/resources/1234/M HTTP/1.1
Host: api.ente.example
Content-Type: application/json

{
  "a": {
    "a1s": [ 1, 2 ],
    "a2": "RGFuJ3MgVG9vbHMgYXJlIGNvb2wh"
  },
  "b": "Stringa di esempio"
}

HTTP/1.1 200 OK
Content-Type: application/json

{"c": "risultato"}

HTTP/1.1 500 Internal Server Error
Content-Type: application/problem+json

{
    "type": "https://apidoc.ente.example/probs/operation-too-long",
    "status": 500,
    "title": "L'operazione è durata troppo.",
    "detail": "Il sistema non e' riuscito a completare in tempo l'operazione prevista."
}

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
    "type": "https://apidoc.ente.example/probs/invalid-a",
    "status": 400,
    "title": "L'attributo \`b\` ha un valore non valido.",
    "detail": "L'attributo \`b\` dev'essere una stringa di lunghezza   inferiore a 32 caratteri."
}

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
    "status": 404,
    "title": "Risorsa non trovata."
}

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
  xmlns:tns="http://ente.example/nome-api"
  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap12/" name="SOAPBlockingImplService" targetNamespace="http://ente.example/nome-api">
  <wsdl:types>
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
      xmlns:tns="http://ente.example/nome-api" attributeFormDefault="unqualified" elementFormDefault="unqualified" targetNamespace="http://ente.example/nome-api">
      <xs:element name="MRequest" type="tns:MRequest"/>
      <xs:element name="MRequestResponse" type="tns:MRequestResponse"/>
      <xs:complexType name="MRequest">
        <xs:sequence>
          <xs:element minOccurs="0" name="M" type="tns:mType"/>
        </xs:sequence>
      </xs:complexType>
      <xs:complexType name="mType">
        <xs:sequence>
          <xs:element minOccurs="0" name="oId" type="xs:int"/>
          <xs:element minOccurs="0" name="a" type="tns:aComplexType"/>
          <xs:element minOccurs="0" name="b" type="xs:string"/>
        </xs:sequence>
      </xs:complexType>
      <xs:complexType name="aComplexType">
        <xs:sequence>
          <xs:element minOccurs="0" name="a1s" type="tns:a1ComplexType"/>
          <xs:element minOccurs="0" name="a2" type="xs:string"/>
        </xs:sequence>
      </xs:complexType>
      <xs:complexType name="a1ComplexType">
        <xs:sequence>
          <xs:element maxOccurs="unbounded" minOccurs="0" name="a1" nillable="true" type="xs:string"/>
        </xs:sequence>
      </xs:complexType>
      <xs:complexType name="MRequestResponse">
        <xs:sequence>
          <xs:element minOccurs="0" name="return" type="tns:mResponseType"/>
        </xs:sequence>
      </xs:complexType>
      <xs:complexType name="mResponseType">
        <xs:sequence>
          <xs:element minOccurs="0" name="c" type="xs:string"/>
        </xs:sequence>
      </xs:complexType>
      <xs:complexType name="errorMessageFault">
        <xs:sequence>
          <xs:element minOccurs="0" name="customFaultCode" type="xs:string"/>
        </xs:sequence>
      </xs:complexType>
      <xs:element name="ErrorMessageFault" nillable="true" type="tns:errorMessageFault"/>
    </xs:schema>
  </wsdl:types>
  <wsdl:message name="MRequest">
    <wsdl:part element="tns:MRequest" name="parameters"/>
  </wsdl:message>
  <wsdl:message name="MRequestResponse">
    <wsdl:part element="tns:MRequestResponse" name="parameters"/>
  </wsdl:message>
  <wsdl:message name="ErrorMessageException">
    <wsdl:part element="tns:ErrorMessageFault" name="ErrorMessageException"/>
  </wsdl:message>
  <wsdl:portType name="SOAPBlockingImpl">
    <wsdl:operation name="MRequest">
      <wsdl:input message="tns:MRequest" name="MRequest"/>
      <wsdl:output message="tns:MRequestResponse" name="MRequestResponse"/>
      <wsdl:fault message="tns:ErrorMessageException" name="ErrorMessageException"/>
    </wsdl:operation>
  </wsdl:portType>
  <wsdl:binding name="SOAPBlockingImplServiceSoapBinding" type="tns:SOAPBlockingImpl">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="MRequest">
      <soap:operation soapAction="" style="document"/>
      <wsdl:input name="MRequest">
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output name="MRequestResponse">
        <soap:body use="literal"/>
      </wsdl:output>
      <wsdl:fault name="ErrorMessageException">
        <soap:fault name="ErrorMessageException" use="literal"/>
      </wsdl:fault>
    </wsdl:operation>
  </wsdl:binding>
  <wsdl:service name="SOAPBlockingImplService">
    <wsdl:port binding="tns:SOAPBlockingImplServiceSoapBinding" name="SOAPBlockingImplPort">
      <soap:address location="https://api.ente.example/soap/nome-api/v1"/>
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:m="http://ente.example/nome-api">
    <soap:Header>
        <!--Autenticazione-->
    </soap:Header>
    <soap:Body>
        <m:MRequest>
            <M>
                <oId>1234</oId>
                <a>
                    <a1s>
                        <a1>1</a1>
                        ...                       
                        <a1>2</a1>
                    </a1s>
                    <a2>RGFuJ3MgVG9vbHMgYXJlIGNvb2wh</a2>
                </a>
                <b>Stringa di esempio</b>
            </M>
        </m:MRequest>
    </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:m="http://ente.example/nome-api">

    <soap:Body>
        <m:MRequestResponse>
            <return>
                <m:c>OK</m:c>
            </return>
        </m:MRequestResponse>
    </soap:Body>

</soap:Envelope>

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:m="http://ente.example/nome-api">
    <soap:Body>
        <soap:Fault>
            <soap:Code>
                <soap:Value>soap:Receiver</soap:Value>
            </soap:Code>
            <soap:Reason>
                <soap:Text xml:lang="en">Error</soap:Text>
            </soap:Reason>
            <soap:Detail>
                <m:ErrorMessageFault>
                    <customFaultCode>1234</customFaultCode>
                </m:ErrorMessageFault>
            </soap:Detail>
        </soap:Fault>
    </soap:Body>
</soap:Envelope>

Pattern non bloccanti¶

I pattern di interazione non bloccanti di tipo RPC-like sono quelli in cui un fruitore invia una richiesta e questa viene solo presa in carico immediatamente, mentre il suo soddisfacimento può avvenire in maniera differita. Gli approcci non bloccanti vengono utilizzati nei casi in cui i tempi per l’erogazione di una risposta da parte dell’erogatore sono lunghi perché

• la richiesta è onerosa in termini temporali;
• l’erogatore non può farsi immediatamente carico dell’erogazione del servizio.

Al fine di collegare le richieste con le risposte si farà uso, sia nelle implementazioni SOAP che in quelle REST, di meta-informazioni specifiche (quali il CorrelationID e l’endpoint per le callback). Queste sono estranee solitamente alla business logic del servizio, ma è necessario definirle a livello di API ai fini dell’interoperabilità. A tal fine verranno definiti header (HTTP nel caso REST ed envelope nel caso SOAP) utili a contenere queste informazioni. In alcuni casi, una API viene creata al fine di automatizzare o semplificare un servizio già offerto dalla pubblica amministrazione. In una moltitudine di casi questi servizi sono asincroni (non bloccanti) per natura, e consistono di richieste a cui vengono allegati degli identificativi (es. numeri di protocollo) che accompagnano la richiesta. In questi casi, il CorrelationID può essere sostituito da questi identificativi già previsti dal servizio.

Nel seguito, per gli esempi proposti si fa riferimento ad un’amministrazione denominata ente.example che offre un’interfaccia di servizio secondo le due diverse tecnologie REST o SOAP. Inoltre, per quanto riguarda i pattern relativi a chiamata a procedura remota (bloccante e non bloccante), si farà riferimento ad un metodo M che accetta come parametri:

• a, un oggetto contenente a sua volta un array a1 di interi ed una stringa a2;
• b, una stringa;

e restituisce una stringa c come output.

Le implementazioni degli esempi sono corredate dalla specifica dell’interfaccia e da uno scambio di messaggi esemplificativo.

Di seguito le indicazioni per le tecnologie accolte dal ModI.

L’AgID assicura l’aggiornamento degli stessi per soddisfare le esigenze espresse dalle PA.

openapi: 3.0.1
info:
 title: RESTCallbackServer
 version: "1.0"
 description: |-
   Questo file descrive semplicemente i metodi di un'API
   e non indica tutte le informazioni di metadatazione che
   normalmente vanno inserite.
 license:
   name: Apache 2.0 License
   url: http://www.apache.org/licenses/LICENSE-2.0.html
paths:
 /resources/{id_resource}/M:
   post:
     description: M
     operationId: PushMessage
     parameters:
     - name: X-ReplyTo
       in: header
       schema:
         type: string
     - name: id_resource
       in: path
       required: true
       schema:
         type: integer
         format: int32
     requestBody:
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/MType'
     responses:
       202:
         description: Preso carico correttamente di M
         headers:
           X-Correlation-ID:
             required: true
             schema:
               type: string
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/ACKMessage'
       400:
         description: Richiesta non valida
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/ErrorMessage'
       404:
         description: Identificativo non trovato
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/ErrorMessage'
       default:
         $ref: '#/components/responses/default'
     callbacks:
       completionCallback:
         '{$request.header#/X-ReplyTo}':
           post:
             requestBody:
               content:
                 application/json:
                   schema:
                     $ref: '#/components/schemas/MResponseType'
             responses:
               200:
                 description: Risposta correttamente ricevuta
                 content:
                   application/json:
                     schema:
                       $ref: '#/components/schemas/ACKMessage'

               default:
                 $ref: '#/components/responses/default'
components:
 responses:

   default:
     description: |-
       Errore inatteso. Non ritornare informazioni
       sulla logica interna e/o non pertinenti all'interfaccia.
     content:
       application/json:
         schema:
           $ref: '#/components/schemas/ErrorMessage'
 schemas:
   MType:
     type: object
     properties:
       a:
         $ref: '#/components/schemas/AComplexType'
       b:
         type: string
   ACKMessage:
     type: object
     properties:
       outcome:
         type: string
   MResponseType:
     type: object
     properties:
       c:
         type: string
   AComplexType:
     type: object
     properties:
       a1s:
         type: array
         items:
           type: integer
           format: int32
       a2:
         type: string
   ErrorMessage:
      type: object
      properties:
        detail:
          description: |
            A human readable explanation specific to this occurrence of the
            problem.
          type: string
        instance:
          description: |
            An absolute URI that identifies the specific occurrence of the problem.
            It may or may not yield further information if dereferenced.
          format: uri
          type: string
        status:
          description: |
            The HTTP status code generated by the origin server for this occurrence
            of the problem.
          exclusiveMaximum: true
          format: int32
          maximum: 600
          minimum: 100
          type: integer
        title:
          description: |
            A short, summary of the problem type. Written in english and readable
            for engineers (usually not suited for non technical stakeholders and
            not localized); example: Service Unavailable
          type: string
        type:
          default: about:blank
          description: |
            An absolute URI that identifies the problem type.  When dereferenced,
            it SHOULD provide human-readable documentation for the problem type
            (e.g., using HTML).
          format: uri
          type: string

openapi: 3.0.1
info:
 title: RESTCallbackClient
 version: "1.0"
 description: |-
   Questo file descrive semplicemente i metodi di un'API
   e non indica tutte le informazioni di metadatazione che
   normalmente vanno inserite.
 license:
   name: Apache 2.0 License
   url: http://www.apache.org/licenses/LICENSE-2.0.html
paths:
 /MResponse:
   post:
     description: M
     operationId: PushResponseMessage
     parameters:
     - name: X-Correlation-ID
       in: header
       schema:
         type: string
     requestBody:
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/MResponseType'
     responses:
       200:
         description: Risposta correttamente ricevuta
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/ACKMessage'
       400:
         description: Richiesta non valida
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/ErrorMessage'
       404:
         description: Identificativo non trovato
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/ErrorMessage'
       default:
         description: |-
           Errore inatteso. Non ritornare informazioni
           sulla logica interna e/o non pertinenti all'interfaccia.
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/ErrorMessage'

components:
 schemas:
   ACKMessage:
     type: object
     properties:
       outcome:
         type: string
   MResponseType:
     type: object
     properties:
       c:
         type: string
   ErrorMessage:
      type: object
      properties:
        detail:
          description: |
            A human readable explanation specific to this occurrence of the
            problem.
          type: string
        instance:
          description: |
            An absolute URI that identifies the specific occurrence of the problem.
            It may or may not yield further information if dereferenced.
          format: uri
          type: string
        status:
          description: |
            The HTTP status code generated by the origin server for this occurrence
            of the problem.
          exclusiveMaximum: true
          format: int32
          maximum: 600
          minimum: 100
          type: integer
        title:
          description: |
            A short, summary of the problem type. Written in english and readable
            for engineers (usually not suited for non technical stakeholders and
            not localized); example: Service Unavailable
          type: string
        type:
          default: about:blank
          description: |
            An absolute URI that identifies the problem type.  When dereferenced,
            it SHOULD provide human-readable documentation for the problem type
            (e.g., using HTML).
          format: uri
          type: string

POST /rest/nome-api/v1/resources/1234/M HTTP/1.1
Host: api.ente.example
Content-Type: application/json
X-ReplyTo: https://api.client.example/rest/v1/nomeinterfacciaclient/Mresponse

{
  "a": {
    "a1": [ 1, "..", 2 ],
    "a2": "RGFuJ3MgVG9vbHMgYXJlIGNvb2wh"
  },
  "b": "Stringa di esempio"
}

HTTP/1.1 202 Accepted
Content-Type: application/json
X-Correlation-ID: 69a445fb-6a9f-44fe-b1c3-59c0f7fb568d

{"result": "ACK"}

POST /rest/v1/nomeinterfacciaclient/Mresponse HTTP/1.1
Host: api.client.example
Content-Type: application/json
X-Correlation-ID: 69a445fb-6a9f-44fe-b1c3-59c0f7fb568d

{"c": "OK"}

HTTP/1.1 200 OK
Content-Type: application/json

{"result": "ACK"}

<?xml version="1.0"?>
<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns="http://ente.example/nome-api"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap12/" 
    name="SOAPCallbackServerService" 
    targetNamespace="http://ente.example/nome-api">
    <wsdl:types>
        <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:tns="http://ente.example/nome-api" attributeFormDefault="unqualified" elementFormDefault="unqualified" targetNamespace="http://ente.example/nome-api">

            <xs:element name="MRequest" type="tns:MRequest"/>
            <xs:element name="MRequestResponse" type="tns:MRequestResponse"/>

            <xs:element name="ErrorMessageFault" nillable="true" type="tns:errorMessageFault"/>
            <xs:element name="X-ReplyTo" nillable="true" type="xs:string"/>
            <xs:element name="X-Correlation-ID" nillable="true" type="xs:string"/>

            <xs:complexType name="MRequest">
                <xs:sequence>
                    <xs:element minOccurs="0" name="M" type="tns:mType"/>
                </xs:sequence>
            </xs:complexType>

            <xs:complexType name="mType">
                <xs:sequence>
                    <xs:element minOccurs="0" name="o_id" type="xs:int"/>
                    <xs:element minOccurs="0" name="a" type="tns:aComplexType"/>
                    <xs:element minOccurs="0" name="b" type="xs:string"/>
                </xs:sequence>
            </xs:complexType>

            <xs:complexType name="aComplexType">
                <xs:sequence>
                    <xs:element maxOccurs="unbounded" minOccurs="0" name="a1s" nillable="true" type="xs:string"/>
                    <xs:element minOccurs="0" name="a2" type="xs:string"/>
                </xs:sequence>
            </xs:complexType>

            <xs:complexType name="MRequestResponse">
                <xs:sequence>
                    <xs:element minOccurs="0" name="return" type="tns:ackMessage"/>
                </xs:sequence>
            </xs:complexType>

            <xs:complexType name="ackMessage">
                <xs:sequence>
                    <xs:element minOccurs="0" name="outcome" type="xs:string"/>
                </xs:sequence>
            </xs:complexType>

            <xs:complexType name="errorMessageFault">
                <xs:sequence>
                    <xs:element minOccurs="0" name="customFaultCode" type="xs:string"/>
                </xs:sequence>
            </xs:complexType>
        </xs:schema>
    </wsdl:types>

    <wsdl:message name="MRequest">
        <wsdl:part element="tns:MRequest" name="parameters"/>
        <wsdl:part element="tns:X-ReplyTo" name="X-ReplyTo"/>
    </wsdl:message>

    <wsdl:message name="MRequestResponse">
        <wsdl:part element="tns:MRequestResponse" name="result"/>
        <wsdl:part element="tns:X-Correlation-ID" name="X-Correlation-ID"/>
    </wsdl:message>

    <wsdl:message name="ErrorMessageException">
        <wsdl:part element="tns:ErrorMessageFault" name="ErrorMessageException"/>
    </wsdl:message>

    <wsdl:portType name="SOAPCallback">
        <wsdl:operation name="MRequest">
            <wsdl:input message="tns:MRequest" name="MRequest"/>
            <wsdl:output message="tns:MRequestResponse" name="MRequestResponse"/>
            <wsdl:fault message="tns:ErrorMessageException" name="ErrorMessageException"/>
        </wsdl:operation>
    </wsdl:portType>

    <wsdl:binding name="SOAPCallbackServiceSoapBinding" type="tns:SOAPCallback">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
        <wsdl:operation name="MRequest">
            <soap:operation soapAction="" style="document"/>
            <wsdl:input name="MRequest">
                <soap:header message="tns:MRequest" part="X-ReplyTo" use="literal"/>
                <soap:body parts="parameters" use="literal"/>
            </wsdl:input>
            <wsdl:output name="MRequestResponse">
                <soap:header message="tns:MRequestResponse" part="X-Correlation-ID" use="literal"/>
                <soap:body parts="result" use="literal"/>
            </wsdl:output>
            <wsdl:fault name="ErrorMessageException">
                <soap:fault name="ErrorMessageException" use="literal"/>
            </wsdl:fault>
        </wsdl:operation>
    </wsdl:binding>

    <wsdl:service name="SOAPCallbackService">
        <wsdl:port name="SOAPCallbackPort" binding="tns:SOAPCallbackServiceSoapBinding">
            <soap:address location="https://api.ente.example/soap/nome-api/v1"/>
        </wsdl:port>
    </wsdl:service>

</wsdl:definitions>

<?xml version='1.0' encoding='UTF-8'?>
<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns="http://ente.example/nome-api"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap12/" 
    name="SOAPCallbackClientInterfaceService" 
    targetNamespace="http://ente.example/nome-api">
    <wsdl:types>
        <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:tns="http://ente.example/nome-api" attributeFormDefault="unqualified" elementFormDefault="unqualified" targetNamespace="http://ente.example/nome-api">

            <xs:element name="MRequestResponse" type="tns:MRequestResponse"/>

            <xs:element name="MRequestResponseResponse" type="tns:MRequestResponseResponse"/>
            
            <xs:element name="X-Correlation-ID" nillable="true" type="xs:string"/>

            <xs:complexType name="MRequestResponse">
                <xs:sequence>
                    <xs:element minOccurs="0" name="return" type="tns:mResponseType"/>
                </xs:sequence>
            </xs:complexType>

            <xs:complexType name="mResponseType">
                <xs:sequence>
                    <xs:element minOccurs="0" name="c" type="xs:string"/>
                </xs:sequence>
            </xs:complexType>

            <xs:complexType name="MRequestResponseResponse">
                <xs:sequence>
                    <xs:element minOccurs="0" name="return" type="tns:ackMessage"/>
                </xs:sequence>
            </xs:complexType>

            <xs:complexType name="ackMessage">
                <xs:sequence>
                    <xs:element minOccurs="0" name="outcome" type="xs:string"/>
                </xs:sequence>
            </xs:complexType>
        </xs:schema>
    </wsdl:types>

    <wsdl:message name="MRequestResponse">
        <wsdl:part element="tns:MRequestResponse" name="parameters"/>
        <wsdl:part element="tns:X-Correlation-ID" name="X-Correlation-ID"/>
    </wsdl:message>

    <wsdl:message name="MRequestResponseResponse">
        <wsdl:part element="tns:MRequestResponseResponse" name="result"/>
    </wsdl:message>

    <wsdl:portType name="SOAPCallbackClient">
        <wsdl:operation name="MRequestResponse">
            <wsdl:input message="tns:MRequestResponse" name="MRequestResponse"/>
            <wsdl:output message="tns:MRequestResponseResponse" name="MRequestResponseResponse"/>
        </wsdl:operation>
    </wsdl:portType>

    <wsdl:binding name="SOAPCallbackClientServiceSoapBinding" type="tns:SOAPCallbackClient">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
        <wsdl:operation name="MRequestResponse">
            <soap:operation soapAction="" style="document"/>
            <wsdl:input name="MRequestResponse">
                <soap:header message="tns:MRequestResponse" part="X-Correlation-ID" use="literal"/>
                <soap:body parts="parameters" use="literal"/>
            </wsdl:input>
            <wsdl:output name="MRequestResponseResponse">
                <soap:body parts="result" use="literal" />
            </wsdl:output>
        </wsdl:operation>
    </wsdl:binding>
    
    <wsdl:service name="SOAPCallbackClientService">
        <wsdl:port binding="tns:SOAPCallbackClientServiceSoapBinding" name="SOAPCallbackClientPort">
            <soap:address location="https://api.client.example/soap/nome-api/v1"/>
        </wsdl:port>
    </wsdl:service>
</wsdl:definitions>

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:m="http://ente.example/nome-api">
    <soap:Header>
        <m:X-ReplyTo>https://api.client.example/soap/nome-api/v1</m:X-ReplyTo>
    </soap:Header>
    <soap:Body>
        <m:MRequest>
            <M>
                <o_id>1234</o_id>
                <a>
                    <a1s>1</a1s>
                    <a2>prova</a2>
                </a>
                <b>prova</b>
            </M>
        </m:MRequest>
    </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:m="http://ente.example/nome-api">>
    <soap:Header>
        <m:X-Correlation-ID>b8268033-de67-4fa0-bf06-caebbfa5117a</m:X-Correlation-ID>
    </soap:Header>
    <soap:Body>
        <m:MRequestResponse>
            <return>
                <outcome>ACCEPTED</outcome>
            </return>
        </m:MRequestResponse>
    </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:m="http://ente.example/nome-api">
    <soap:Header>
        <m:X-Correlation-ID>b8268033-de67-4fa0-bf06-caebbfa5117a</m:X-Correlation-ID>
    </soap:Header>
    <soap:Body>
        <m:MRequestResponse>
            <return>
                <c>OK</c>
            </return>
        </m:MRequestResponse>
    </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:m="http://ente.example/nome-api">
    <soap:Body>
        <m:MRequestResponseResponse>
            <return>
                <outcome>OK</outcome>
            </return>
        </m:MRequestResponseResponse>
    </soap:Body>
</soap:Envelope>

openapi: 3.0.1
info:
 title: RESTbusywaiting
 version: "1.0"
 description: |-
   Questo file descrive semplicemente i metodi di un'API
   e non indica tutte le informazioni di metadatazione che
   normalmente vanno inserite.
 license:
   name: Apache 2.0 License
   url: http://www.apache.org/licenses/LICENSE-2.0.html
paths:
  /tasks/queue:
    post:
      description: Crea in maniera asincrona un task o una risorsa.
      operationId: PushMessage
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MType'
      responses:
        202:
          description: Preso carico correttamente
          headers:
            Location:
              description: URL dove verificare lo stato
              required: true
              schema:
                type: string
                format: uri
        '400':
          $ref: '#/components/responses/400BadRequest'

        default:
          $ref: '#/components/responses/default'
  /tasks/queue/{id_task}/:
    get:
      description: Verifica lo stato del task o risorsa
      operationId: CheckStatus
      parameters:
      - $ref: '#/components/parameters/id_task'
      responses:
        200:
          description: |-
            Lo stato del task o della risorsa.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskStatus'
        '303':
          description: Task Completato
          content:
              application/json:
                schema:
                  $ref: '#/components/schemas/TaskStatus'
          headers:
              Location:
                description: URL dove prelevare il risultato
                required: true
                schema:
                  type: string
                  format: uri
        '400':
          $ref: '#/components/responses/400BadRequest'
        '404':
          $ref: '#/components/responses/404NotFound'
        default:
          $ref: '#/components/responses/default'
  /tasks/result/{id_task}/:
    get:
      description: Recupera il risultato del task o la risorsa
      operationId: RetriveResource
      parameters:
      - $ref: '#/components/parameters/id_task'
      responses:
        200:
          description:  Il risultato del task o la risorsa
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MResponseType'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '404':
          $ref: '#/components/responses/404NotFound'
        default:
          $ref: '#/components/responses/default'
components:
  parameters:
    id_task:
      name: id_task
      in: path
      required: true
      schema:
        type: string
  responses:
    400BadRequest:
      description: Richiesta non accoglibile
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    404NotFound:
      description: Identificativo non trovato
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    default:
      description: |-
        Errore inatteso. Questo viene ritornato nel caso ci sia
        un errore inatteso. Non vanno mai esposti i dati interni
        del server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
  schemas:
    TaskStatus:
      type: object
      properties:
        status:
          type: string
          enum: [pending, completed]
          example: pending
        message:
          type: string
    MType:
      type: object
      properties:
        a:
          $ref: '#/components/schemas/AComplexType'
        b:
          type: string
    MResponseType:
      type: object
      properties:
        c:
          type: string

    AComplexType:
      type: object
      properties:
        a1s:
          type: array
          items:
            type: string
        a2:
          type: string
    ErrorMessage:
      type: object
      properties:
        detail:
          description: |
            A human readable explanation specific to this occurrence of the
            problem.
          type: string
        instance:
          description: |
            An absolute URI that identifies the specific occurrence of the problem.
            It may or may not yield further information if dereferenced.
          format: uri
          type: string
        status:
          description: |
            The HTTP status code generated by the origin server for this occurrence
            of the problem.
          exclusiveMaximum: true
          format: int32
          maximum: 600
          minimum: 100
          type: integer
        title:
          description: |
            A short, summary of the problem type. Written in english and readable
            for engineers (usually not suited for non technical stakeholders and
            not localized); example: Service Unavailable
          type: string
        type:
          default: about:blank
          description: |
            An absolute URI that identifies the problem type.  When dereferenced,
            it SHOULD provide human-readable documentation for the problem type
            (e.g., using HTML).
          format: uri
          type: string

POST /rest/nome-api/v1/resources/1234/M HTTP/1.1
Host: api.ente.example
Content-Type: application/json

{
  "a": {
     "a1": [1, "…", 2],
     "a2": "Stringa di esempio"
  },
  "b": "Stringa di esempio"
}

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /rest/nome-api/v1/resources/1234/M/8131edc0

{
  "status": "accepted",
  "message": "Preso carico della richiesta",
  "id": "8131edc0"
}

GET /rest/nome-api/v1/resources/1234/M/8131edc0 HTTP/1.1
Host: api.ente.example

HTTP/1.1 200 OK
Host: api.ente.example
Content-Type: application/json

{
  "status": "processing",
  "message": "Richiesta in fase di processamento"
}

HTTP/1.1 303 See Other
Content-Type: application/json
Content-Location: /rest/nome-api/v1/resources/1234/M/8131edc0
Location: /rest/nome-api/v1/resources/1234/M/8131edc0/result

{
  "status": "done",
  "message": "Processamento completo",
  "href": "https://api.ente.example/rest/nome-api/v1/resources/1234/M/8131edc0/result"
}

GET /rest/nome-api/v1/resources/1234/M/8131edc0/result HTTP/1.1
Host: api.ente.example

HTTP/1.1 200 OK
Host: api.ente.example
Content-Type: application/json

{"c": "OK"}

<?xml version='1.0' encoding='UTF-8'?>
<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns="http://ente.example/nome-api"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap12/" 
    name="SOAPPullService" 
    targetNamespace="http://ente.example/nome-api">
    <wsdl:types>
        <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:tns="http://ente.example/nome-api" attributeFormDefault="unqualified" elementFormDefault="unqualified" targetNamespace="http://ente.example/nome-api">

            <xs:element name="MProcessingStatus" type="tns:MProcessingStatus" />
            <xs:element name="MProcessingStatusResponse" type="tns:MProcessingStatusResponse" />

            <xs:element name="MRequest" type="tns:MRequest" />
            <xs:element name="MRequestResponse" type="tns:MRequestResponse" />

            <xs:element name="MResponse" type="tns:MResponse" />
            <xs:element name="MResponseResponse" type="tns:MResponseResponse" />

            <xs:element name="ErrorMessageFault" nillable="true" type="tns:errorMessageFault" />
            <xs:element name="X-Correlation-ID" nillable="true" type="xs:string" />

            <xs:complexType name="MProcessingStatus"/>
            <xs:complexType name="MProcessingStatusResponse">
                <xs:sequence>
                    <xs:element name="return" type="tns:processingStatus" />
                </xs:sequence>
            </xs:complexType>

            <xs:complexType name="MRequest">
                <xs:sequence>
                    <xs:element name="M" type="tns:mType" />
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="MRequestResponse">
                <xs:sequence>
                    <xs:element minOccurs="0" name="return" type="tns:processingStatus" />
                </xs:sequence>
            </xs:complexType>

            <xs:complexType name="MResponse"/>
            <xs:complexType name="MResponseResponse">
                <xs:sequence>
                    <xs:element minOccurs="0" name="return" type="tns:mResponseType" />
                </xs:sequence>
            </xs:complexType>

            <xs:complexType name="mType">
                <xs:sequence>
                    <xs:element minOccurs="0" name="o_id" type="xs:int" />
                    <xs:element minOccurs="0" name="a" type="tns:aComplexType" />
                    <xs:element minOccurs="0" name="b" type="xs:string" />
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="aComplexType">
                <xs:sequence>
                    <xs:element maxOccurs="unbounded" minOccurs="0" name="a1s" nillable="true" type="xs:string" />
                    <xs:element minOccurs="0" name="a2" type="xs:string" />
                </xs:sequence>
            </xs:complexType>

            <xs:complexType name="processingStatus">
                <xs:sequence>
                    <xs:element name="status" type="xs:string" />
                    <xs:element name="message" type="xs:string" />
                </xs:sequence>
            </xs:complexType>

            <xs:complexType name="mResponseType">
                <xs:sequence>
                    <xs:element minOccurs="0" name="c" type="xs:string" />
                </xs:sequence>
            </xs:complexType>

            <xs:complexType name="errorMessageFault">
                <xs:sequence>
                    <xs:element name="customFaultCode" type="xs:string" />
                </xs:sequence>
            </xs:complexType>
        </xs:schema>
    </wsdl:types>

    <wsdl:message name="MProcessingStatus">
        <wsdl:part element="tns:MProcessingStatus" name="parameters"/>
        <wsdl:part element="tns:X-Correlation-ID" name="X-Correlation-ID"/>
    </wsdl:message>

    <wsdl:message name="MProcessingStatusResponse">
        <wsdl:part element="tns:MProcessingStatusResponse" name="parameters"/>
    </wsdl:message>

    <wsdl:message name="MRequest">
        <wsdl:part element="tns:MRequest" name="parameters"/>
    </wsdl:message>

    <wsdl:message name="MRequestResponse">
        <wsdl:part element="tns:MRequestResponse" name="result"/>
        <wsdl:part element="tns:X-Correlation-ID" name="X-Correlation-ID"/>
    </wsdl:message>

    <wsdl:message name="MResponse">
        <wsdl:part element="tns:MResponse" name="parameters"/>
        <wsdl:part element="tns:X-Correlation-ID" name="X-Correlation-ID"/>
    </wsdl:message>

    <wsdl:message name="MResponseResponse">
        <wsdl:part element="tns:MResponseResponse" name="parameters"/>
    </wsdl:message>

    <wsdl:message name="ErrorMessageException">
        <wsdl:part element="tns:ErrorMessageFault" name="ErrorMessageException"/>
    </wsdl:message>

    <wsdl:portType name="SOAPPull">
        <wsdl:operation name="MRequest">
            <wsdl:input message="tns:MRequest" name="MRequest"/>
            <wsdl:output message="tns:MRequestResponse" name="MRequestResponse"/>
            <wsdl:fault message="tns:ErrorMessageException" name="ErrorMessageException"/>
        </wsdl:operation>

        <wsdl:operation name="MProcessingStatus">
            <wsdl:input message="tns:MProcessingStatus" name="MProcessingStatus"/>
            <wsdl:output message="tns:MProcessingStatusResponse" name="MProcessingStatusResponse"/>
            <wsdl:fault message="tns:ErrorMessageException" name="ErrorMessageException"/>
        </wsdl:operation>

        <wsdl:operation name="MResponse">
            <wsdl:input message="tns:MResponse" name="MResponse"/>
            <wsdl:output message="tns:MResponseResponse" name="MResponseResponse"/>
            <wsdl:fault message="tns:ErrorMessageException" name="ErrorMessageException"/>
        </wsdl:operation>
    </wsdl:portType>
    
    <wsdl:binding name="SOAPPullServiceSoapBinding" type="tns:SOAPPull">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />

        <wsdl:operation name="MRequest">
            <soap:operation soapAction="" style="document" />

            <wsdl:input name="MRequest">
                <soap:body use="literal" />
            </wsdl:input>

            <wsdl:output name="MRequestResponse">
                <soap:header message="tns:MRequestResponse" part="X-Correlation-ID" use="literal"/>
                <soap:body parts="result" use="literal" />
            </wsdl:output>

            <wsdl:fault name="ErrorMessageException">
                <soap:fault name="ErrorMessageException" use="literal" />
            </wsdl:fault>

        </wsdl:operation>

        <wsdl:operation name="MProcessingStatus">
            <soap:operation soapAction="" style="document" />

            <wsdl:input name="MProcessingStatus">
                <soap:header message="tns:MProcessingStatus" part="X-Correlation-ID" use="literal"/>
                <soap:body parts="parameters" use="literal" />
            </wsdl:input>

            <wsdl:output name="MProcessingStatusResponse">
                <soap:body use="literal" />
            </wsdl:output>

            <wsdl:fault name="ErrorMessageException">
                <soap:fault name="ErrorMessageException" use="literal" />
            </wsdl:fault>

        </wsdl:operation>

        <wsdl:operation name="MResponse">
            <soap:operation soapAction="" style="document" />

            <wsdl:input name="MResponse">
                <soap:header message="tns:MResponse" part="X-Correlation-ID" use="literal"/>
                <soap:body parts="parameters" use="literal" />
            </wsdl:input>

            <wsdl:output name="MResponseResponse">
                <soap:body use="literal" />
            </wsdl:output>

            <wsdl:fault name="ErrorMessageException">
                <soap:fault name="ErrorMessageException" use="literal" />
            </wsdl:fault>
        </wsdl:operation>
    </wsdl:binding>

    <wsdl:service name="SOAPPullService">
        <wsdl:port binding="tns:SOAPPullServiceSoapBinding" name="SOAPPullPort">
            <soap:address location="https://api.ente.example/soap/nome-api/v1" />
        </wsdl:port>
    </wsdl:service>

</wsdl:definitions>

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:m="http://ente.example/nome-api">
    <soap:Body>
        <m:MRequest>
            <M>
                <o_id>1234</o_id>
                <a>
                    <a1s>1</a1s>
                    <a2>prova</a2>
                </a>
                <b>prova</b>
            </M>
        </m:MRequest>
    </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:m="http://ente.example/nome-api">
    <soap:Header>
        <m:X-Correlation-ID>c8e191a8-f34f-41ed-82ea-68e096466707</m:X-Correlation-ID>
    </soap:Header>
    <soap:Body>
        <m:MRequestResponse>
            <return>
                <status>accepted</status>
                <message>Preso carico della richiesta</message>
            </return>
        </m:MRequestResponse>
    </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:m="http://ente.example/nome-api">
    <soap:Header>
        <m:X-Correlation-ID>c8e191a8-f34f-41ed-82ea-68e096466707</m:X-Correlation-ID>
    </soap:Header>
    <soap:Body>
        <m:MProcessingStatus/>
    </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:m="http://ente.example/nome-api">
    <soap:Body>
        <m:MProcessingStatusResponse>
            <return>
                <status>processing</status>
                <message>Richiesta in fase di processamento</message>
            </return>
        </m:MProcessingStatusResponse>
    </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:m="http://ente.example/nome-api">
    <soap:Body>
        <m:MProcessingStatusResponse>
            <return>
                <status>done</status>
                <message>Richiesta completata</message>
            </return>
        </m:MProcessingStatusResponse>
    </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:m="http://ente.example/nome-api">
    <soap:Header>
        <m:X-Correlation-ID>c8e191a8-f34f-41ed-82ea-68e096466707</m:X-Correlation-ID>
    </soap:Header>
    <soap:Body>
        <m:MResponse/>
    </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:m="http://ente.example/nome-api">
    <soap:Body>
        <m:MResponseResponse>
            <return>
                <c>OK</c>
            </return>
        </m:MResponseResponse>
    </soap:Body>
</soap:Envelope>

Accesso CRUD a risorse¶

In un’architettura orientata alle risorse le API vengono utilizzate, più che per eseguire compiti complessi, per eseguire operazioni di tipo CRUD - Create, Read, Update, Delete - su risorse del dominio di interesse. Ad esempio, una prenotazione è una risorsa che può essere creata (quando viene fissata), letta, modificata ed eliminata.

In questo scenario si assume che le API siano utilizzate per la gestione da parte del fruitore delle risorse messe a disposizione dall’erogatore. L’insieme di operazioni CRUD offerte dall’erogatore dipende dalla natura della risorse e dalla relazione costruita con i fruitori: sono possibili relazioni in cui l’erogatore rende disponibile ai fruitori la sola operazione di lettura (Read).

Figura 5 - Interazione CRUD

Il sequence diagram è, come si nota in figura, equivalente a quello di una RPC bloccante. In questo caso la richiesta DEVE contenere:

• Una operazione da effettuare sulla risorsa da scegliere tra Create, Read, Update e Delete;
• Un percorso che indica un identificativo di risorsa (es. una specifica prenotazione) oppure di una collezione di risorse (es. un insieme di prenotazioni);
• Nel caso di una operazione di Create o Update, un pacchetto dati indicante come inizializzare o modificare (anche parzialmente) la risorsa in questione.

Per quanto sia possibile sviluppare funzionalità CRUD anche sviluppando una interfaccia di servizio SOAP, il ModI prevede lo sviluppo di una interfaccia REST.

openapi: 3.0.1
info:
  title: RESTCRUD
  version: "1.0"
  description: |-
    Questo file descrive semplicemente i metodi di un'API
    e non indica tutte le informazioni di metadatazione che
    normalmente vanno inserite.
  license:
    name: Apache 2.0 License
    url: http://www.apache.org/licenses/LICENSE-2.0.html
paths:
  /municipio/{id_municipio}/ufficio/{id_ufficio}/prenotazioni:
    get:
      description: Mostra prenotazioni
      operationId: listReservations
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/cursor'
      - $ref: '#/components/parameters/path_id_municipio'
      - $ref: '#/components/parameters/path_id_ufficio'
      responses:
        '200':
          description: Una lista di prenotazioni.
          content:
            application/json:
              schema:
                properties:
                  prenotazioni:
                    type: array
                    items:
                      $ref: '#/components/schemas/Prenotazione'
                  count:
                    type: integer
                    format: int32
                  next:
                    type: string
        '400':
          $ref: '#/components/responses/400BadRequest'
        '404':
          $ref: '#/components/responses/404NotFound'
        default:
          $ref: '#/components/responses/default'

    post:
      description: Aggiungi una prenotazione
      operationId: AddReservation_1
      parameters:
      - $ref: '#/components/parameters/path_id_municipio'
      - $ref: '#/components/parameters/path_id_ufficio'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Prenotazione'
      responses:
        '201':
          description: Prenotazione Creata.
          headers:
            Location:
              description: ID della prenotazione creata
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prenotazione'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '404':
          $ref: '#/components/responses/404NotFound'
        default:
          $ref: '#/components/responses/default'

  /municipio/{id_municipio}/ufficio/{id_ufficio}/prenotazioni/{id_prenotazione}:
    get:
      description: LeggiPrenotazione
      operationId: GetReservation_1
      parameters:
      - $ref: '#/components/parameters/path_id_municipio'
      - $ref: '#/components/parameters/path_id_ufficio'
      - name: id_prenotazione
        in: path
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Prenotazione estratta correttamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prenotazione'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '404':
          $ref: '#/components/responses/404NotFound'
        default:
          $ref: '#/components/responses/default'
    delete:
      description: EliminaPrenotazione
      operationId: DeleteReservation
      parameters:
      - $ref: '#/components/parameters/path_id_municipio'
      - $ref: '#/components/parameters/path_id_ufficio'
      - name: id_prenotazione
        in: path
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Prenotazione eliminata correttamente
        '404':
          $ref: '#/components/responses/404NotFound'
        default:
          $ref: '#/components/responses/default'

    patch:
      description: ModificaPrenotazione
      operationId: PatchReservation
      parameters:
      - $ref: '#/components/parameters/path_id_municipio'
      - $ref: '#/components/parameters/path_id_ufficio'
      - name: id_prenotazione
        in: path
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/PatchPrenotazione'
      responses:
        '200':
          description: Prenotazione modificata correttamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prenotazione'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '404':
          $ref: '#/components/responses/404NotFound'
        default:
          $ref: '#/components/responses/default'
components:
  parameters:
    path_id_municipio:
      name: id_municipio
      in: path
      required: true
      schema:
        type: integer
        format: int32
    path_id_ufficio:
      name: id_ufficio
      in: path
      required: true
      schema:
        type: integer
        format: int32
    limit:
        description: How many items to return at one time (max 100)
        in: query
        name: limit
        schema:
          format: int32
          type: integer
    cursor:
        description: An opaque identifier that points to the next item in the collection.
        example: 01BX9NSMKVXXS5PSP2FATZM123
        in: query
        name: cursor
        schema:
          type: string
  responses:
    400BadRequest:
      description: Richiesta non accoglibile
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    404NotFound:
      description: Identificativo non trovato
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    default:
      description: |-
        Errore inatteso. Questo viene ritornato nel caso ci sia
        un errore inatteso. Non vanno mai esposti i dati interni
        del server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
  schemas:
    TaxCode:
        description: Il codice fiscale.
        example: RSSMRA75L01H501A
        externalDocs:
          url: https://w3id.org/italia/onto/CPV/taxCode
        pattern: /^(?:(?:[B-DF-HJ-NP-TV-Z]|[AEIOU])[AEIOU][AEIOUX]|[B-DF-HJ-NP-TV-Z]{2}[A-Z]){2}[\dLMNP-V]{2}(?:[A-EHLMPR-T](?:[04LQ][1-9MNP-V]|[1256LMRS][\dLMNP-V])|[DHPS][37PT][0L]|[ACELMRT][37PT][01LM])(?:[A-MZ][1-9MNP-V][\dLMNP-V]{2}|[A-M][0L](?:[1-9MNP-V][\dLMNP-V]|[0L][1-9MNP-V]))[A-Z]$/i
        type: string
    Prenotazione:
      type: object
      properties:
        nome:
          type: string
        cognome:
          type: string
        codice_fiscale:
          $ref: '#/components/schemas/TaxCode'
        dettagli:
          $ref: '#/components/schemas/PatchPrenotazione'
    PatchPrenotazione:
      type: object
      properties:
        data:
          type: string
          format: date-time
        motivazione:
          type: string
    ErrorMessage:
      type: object
      properties:
        detail:
          description: |
            A human readable explanation specific to this occurrence of the
            problem.
          type: string
        instance:
          description: |
            An absolute URI that identifies the specific occurrence of the problem.
            It may or may not yield further information if dereferenced.
          format: uri
          type: string
        status:
          description: |
            The HTTP status code generated by the origin server for this occurrence
            of the problem.
          exclusiveMaximum: true
          format: int32
          maximum: 600
          minimum: 100
          type: integer
        title:
          description: |
            A short, summary of the problem type. Written in english and readable
            for engineers (usually not suited for non technical stakeholders and
            not localized); example: Service Unavailable
          type: string
        type:
          default: about:blank
          description: |
            An absolute URI that identifies the problem type.  When dereferenced,
            it SHOULD provide human-readable documentation for the problem type
            (e.g., using HTML).
          format: uri
          type: string

POST /rest/appuntamenti/v1/municipio/{id_municipio}/ufficio/{id_ufficio}/prenotazioni HTTP/1.1
Host: api.ente.example
Content-Type: application/json

{
    "nome_proprio": "Mario",
    "cognome": "Rossi",
    "codice_fiscale": "MRORSS77T05E472I",
    "dettagli": {
        "data": "2018-12-03T14:29:12.137Z",
        "motivazione": "string"
    }
}

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://api.ente.example/rest/appuntamenti/v1/municipio/{id_municipio}/ufficio/{id_ufficio}/prenotazioni/12323254

{
    "id": 12323254,
    "nome_proprio": "Mario",
    "cognome": "Rossi",
    "codice_fiscale": "MRORSS77T05E472I",
    "dettagli": {
        "data": "2018-12-03T14:29:12.137Z",
        "motivazione": "string"
    }
}

GET /rest/appuntamenti/v1/municipio/{id_municipio}/ufficio/{id_ufficio}/prenotazioni/12323254 HTTP/1.1
Host: api.ente.example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 12323254,
    "nome_proprio": "Mario",
    "cognome": "Rossi",
    "codice_fiscale": "MRORSS77T05E472I",
    "dettagli": {
        "data": "2018-12-03T14:29:12.137Z",
        "motivazione": "string"
    }
}

PATCH /rest/appuntamenti/v1/municipio/{id_municipio}/ufficio/{id_ufficio}/prenotazioni/12323254 HTTP/1.1
Host: api.ente.example
Content-Type: application/merge-patch+json

{
    "dettagli": {
        "data": "2018-12-03T14:29:12.137Z",
        "motivazione": "nuova motivazione"
    }
}

HTTP/1.1 200 OK
Content-Type: application/json

{
 "nome_proprio": "Mario",
 "cognome": "Rossi",
 "codice_fiscale": "MRORSS77T05E472I",
 "dettagli": {
     "data": "2018-12-03T14:29:12.137Z",
     "motivazione": "nuova motivazione"
 }
}

PATCH /rest/appuntamenti/v1/municipio/{id_municipio}/ufficio/{id_ufficio}/prenotazioni/12323254 HTTP/1.1
Host: api.ente.example
Content-Type: application/json

    {
      "dettagli": {
            "data": "2018-12-03T14:29:12.137Z",
            "motivazione": "nuova motivazione"
      }
    }

HTTP/1.1 415 Unsupported Media Type
Accept-Patch: application/merge-patch+json

DELETE /rest/appuntamenti/v1/municipio/{id_municipio}/ufficio/{id_ufficio}/prenotazioni/12323254 HTTP/1.1
Host: api.ente.example

HTTP/1.1 200 OK

Introduzione¶

I pattern di sicurezza definiscono le modalità per assicurare che le interazioni tra fruitore ed erogatore siano realizzate nel rispetto delle specifiche esigenze di sicurezza determinate dalla natura delle transazioni realizzate e dalle prescrizioni normative che riguardano le stesse.

I pattern di sicurezza si applicano ai pattern di interazione indicati nel Documento Operativo - Pattern di interazione, e sono scelti dall’erogatore in funzione alle specifiche esigenze applicative in relazione alla natura dei fruitori.

Il Documento operativo descrive i pattern di sicurezza individuati da AgID che gli erogatori DEVONO utilizzare per soddisfare le necessità individuate dai requisiti funzionali e non funzionali delle specifiche interazioni con i propri fruitori.

Data la variabilità nel tempo delle esigenze delle amministrazioni e delle tecnologie abilitanti, nonché considerata la natura incrementale del ModI, l’elenco dei pattern di sicurezza non è da intendersi esaustivo. Nel caso in cui un’amministrazione abbia esigenze non ricoperte nei seguenti pattern di sicurezza DEVE informare AgID, nei modi indicati nel capitolo 7 «Pattern e profili di interoperabilità» delle Linee di indirizzo sull’interoperabilità tecnica delle Pubbliche Amministrazioni. Le tecnologie e standard per assicurare la sicurezza dell’interoperabilità tramite API utilizzabili nel ModI, tra cui OAuth 2.0, sono individuate nelle Linee Guida sulla sicurezza, emanate dall’Agenzia per l’Italia Digitale ai sensi dell’articolo 71 del decreto legislativo 7 marzo 2005, n. 82 (Codice dell’Amministrazione Digitale).

I pattern di sicurezza individuati coprono gli aspetti di comunicazione «sicura» tra i domini delle singole parti. Le parti mantengono la loro autonomia negli aspetti organizzativi e di sicurezza interni al proprio dominio.

I pattern di sicurezza

• definiscono a livello di specifica tecnologica uno «strumento condiviso» utile a favorire l’interoperabilità tra erogatori e fruitori.
• forniscono un comune linguaggio per fruitori ed erogatori utile a trattare le necessità e le caratteristiche delle interfacce di servizio.
• offrono agli sviluppatori le modalità tecniche supportate da standard tecnologici documentati, revisionati e testati per esporre i servizi digitali.

I pattern di sicurezza affrontano il tema della sicurezza su due livelli differenti:

• Canale: definisce le modalità di trasporto dei messaggi tra i confini dei domini delle entità coinvolte.
• Messaggio: definisce le modalità di comunicazione dei messaggi tra componenti interne dei domini delle entità coinvolte.

Ogni pattern di sicurezza è strutturato come segue:

• Descrizione: rappresentazione in linguaggio naturale del profilo con relativi precondizioni e obiettivi.
• Regole di processamento: elenco dei passi da eseguire per implementare il profilo.
• Tracciato: ove presente, fornisce un esempio dei messaggi prodotti nell’interazione.

Gli erogatori, ove necessario in accordo con i fruitori, a seguito dell’analisi dei requisiti realizzata, per individuare le proprie esigenze funzionali e non funzionali, DOVREBBERO:

• individuare tra i pattern di interazione (vedi Documento operativo - Pattern di interazione) quelli che soddisfano le proprie esigenze;
• individuare tra i pattern di sicurezza quelli che soddisfano le proprie esigenze;
• implementare le interfacce di servizio attraverso la combinazione dei pattern di interazione e di pattern di sicurezza.

L’individuazione dei pattern di sicurezza DEVE ricoprire solamente i requisiti necessari.

Il Trust è uno dei mezzi più importanti per gestire le problematiche di sicurezza nello scambio di informazione in rete per consentire l’interoperabilità tra i sistemi. Esso si basa sul reciproco riconoscimento delle entità interagenti e sulla fiducia nei rispettivi comportamenti.

Nel presente Documento operativo, per direct trust si intende la relazione di fiducia tra fruitore ed erogatore, stabilita in modalità diretta, attraverso accordi che si basano sulla condivisione del reciproco modus operandi.

Si rimanda alle Linee Guida sulla sicurezza, emanate dall’Agenzia per l’Italia Digitale ai sensi dell’articolo 71 del decreto legislativo 7 marzo 2005, n. 82 (Codice dell’Amministrazione Digitale), in merito agli algoritmi utilizzabili per la corretta implementazione dei pattern di sicurezza.

Ambito di applicazione¶

Il presente Documento operativo, allegato delle Linee Guida sull’interoperabilità tecnica delle Pubbliche Amministrazioni, definisce i pattern di sicurezza definiti nel ModI

Riferimenti e sigle¶

Sicurezza di canale e/o identificazione delle organizzazioni¶

Di seguito le indicazioni per le tecnologie accolte dal ModI.

L’AgID assicura l’aggiornamento degli stessi per soddisfare le esigenze espresse dalle PA.

Accesso del soggetto fruitore¶

Di seguito le indicazioni per le tecnologie accolte dal ModI.

L’AgID assicura l’aggiornamento degli stessi per soddisfare le esigenze espresse dalle PA.

soap="http://www.w3.org/2003/05/soap-envelope"
wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
ds="http://www.w3.org/2000/09/xmldsig#"
ec="http://www.w3.org/2001/10/xml-exc-c14n#"

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Header>
    <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
      xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" soap:mustUnderstand="1">
      <wsse:BinarySecurityToken EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary" ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3" wsu:Id="X509-39011475-65d5-446e-ba38-be84220fd720">MIICqDCCAZCgAwIBAgIEXLSSUTANBgkqhkiG9w0BAQsFADAW...</wsse:BinarySecurityToken>
      <wsu:Timestamp wsu:Id="TS-819df7b7-379d-48f7-8d9c-28c5b5d252f0">
        <wsu:Created>2019-04-15T14:53:34.649Z</wsu:Created>
        <wsu:Expires>2019-04-15T14:58:34.649Z</wsu:Expires>
      </wsu:Timestamp>
      <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#" Id="SIG-6e09e972-cbe6-43fc-a10c-38e6dce56dbe">
        <ds:SignedInfo>
          <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
            <ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="soap"/>
          </ds:CanonicalizationMethod>
          <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
          <ds:Reference URI="#TS-819df7b7-379d-48f7-8d9c-28c5b5d252f0">
            <ds:Transforms>
              <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
                <ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="soap    wsse"/>
              </ds:Transform>
            </ds:Transforms>
            <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
            <ds:DigestValue>K/3Fq1fYjG5PXv8UlKBuT4XBCWudGR5w2M10wPcZ/Yo=**</ds:DigestValue>
          </ds:Reference>
          <ds:Reference URI="#id-96f9b013-17e5-489d-8068-52c3f1345c75">
            <ds:Transforms>
              <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
                <ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="soap"/>
              </ds:Transform>
            </ds:Transforms>
            <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
            <ds:DigestValue>eH3Vlc3l19NbBawDOuFDN11BfmbgGAnl6Z4LpJVM3UM=**</ds:DigestValue>
          </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>jAtZqkfRcFJW+jx9YDv+r2Q8V4IWEWLAZckZlWsmo...</ds:SignatureValue>
        <ds:KeyInfo Id="KI-32484d1e-867e-4465-a96f-52a8668d5a0c">
          <wsse:SecurityTokenReference xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
            xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="STR-3cf69cce-c56f-461a-905d-dfc20ab0742c">
            <wsse:Reference URI="#X509-39011475-65d5-446e-ba38-be84220fd720" ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"/>
          </wsse:SecurityTokenReference>
        </ds:KeyInfo>
      </ds:Signature>
    </wsse:Security>
    <Action xmlns="http://www.w3.org/2005/08/addressing">http://profile.security.modi.agid.org/HelloWorld/sayHi</Action>
    <MessageID xmlns="http://www.w3.org/2005/08/addressing">urn:uuid:55e6bc57-2286-4b7d-82a9-fdbcf57721b1</MessageID>
    <To xmlns="http://www.w3.org/2005/08/addressing"
      xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="id-96f9b013-17e5-489d-8068-52c3f1345c75">https://api.ente.example/soap/echo/v1</To>
    <ReplyTo xmlns="http://www.w3.org/2005/08/addressing">
      <Address>http://www.w3.org/2005/08/addressing/anonymous</Address>
    </ReplyTo>
  </soap:Header>
  <soap:Body>
    <ns2:sayHi xmlns:ns2="http://profile.security.modi.agid.org/">
      <arg0>OK</arg0>
    </ns2:sayHi>
  </soap:Body>
</soap:Envelope>

soap="http://schemas.xmlsoap.org/soap/envelope/"
wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
ds="http://www.w3.org/2000/09/xmldsig#"
ec="http://www.w3.org/2001/10/xml-exc-c14n#"

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
      xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" soap:mustUnderstand="1">
      <wsse:BinarySecurityToken EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary" ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3" wsu:Id="X509-bf881daf-371a-4d18-9502-d9f92af9a949">MIICqDCCAZ
                CgAwIBAgIEXLSSUTANBgkqhkiG9w0BAQsFADAWMRQwEgYDVQQDDAttb2RpU2VjUHJvZjA
                eFw0xOTA0MTUxNDE2NDlaFw0yNDA0MTUxNDE2NDlaMBYxFDASBgNVBAMMC21vZGlTZWNQ
                cm9mMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvBJNKBiLS+ZcmwGUku5l2
                FKeHogeSZejjOOrO2Ag6DGPXo1MtHt2XwgUXmgT+v0IjhZp5XH2XbwSWw2EMWSG3Zz0CJ
                ILqWGPg0M/LxaIZAxSdxJpVNWg/profO+xKz0B6QHK+I0yecHg7TtI4es9AuDyR4pKslp
                cXyMEqJQ7m5N8v2e4WldeHF2SRN/ereEOuewEi15c7akh4TdkGdiwOSif2AXIugHRgdpH
                jH86iJxFu24IJmBA7C5tytz7mfKollGhI9+2d0902ayVshCV4/pmnX0pDiGayV1C6SDPT
                bapXKXJrp1+fBHaUkDY+W/2Q9sC4o8pttmcpHeMRxFDkwIDAQABMA0GCSqGSIb3DQEBCw
                UAA4IBAQALwKbIm8S2BpYpHaqMwJLeWBPCaDeT7J+KDj39Ac3YxDb8E/hGM+Hn1mq2ssY
                qu5JTvuAQ9o8v3UpcIct15RPgOKYfBzxnH1h2vCavpiFCFTc6UoQgPBZGyyNOOKNOxEnX
                tW7ff1gl2GRLIWXlXDf1fdX7VJVBqWfBvivhIbsDa5LRBCrNsXORx2azUb5QBgMm2UZJx
                YA3+dFRgYmLSY/RyRLf0o03lwCRhAyrU7ya9IMYgrxgjEos2fHB2IGJJ1Wh+gTQWMP+wJ
                ymlC0qyjTHx5pyZOzJGtH5HnaVU7EgtxdBRC9dTlWVpNgmD8nS6Yr/am5cZJZrkIHRyfx
                qkA2W
      </wsse:BinarySecurityToken>
      <wsu:Timestamp wsu:Id="TS-09f1357c-beb4-4804-9410-76c5a06e2e48">
        <wsu:Created>2019-04-15T15:02:15.515Z</wsu:Created>
        <wsu:Expires>2019-04-15T15:07:15.515Z</wsu:Expires>
      </wsu:Timestamp>
      <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#" Id="SIG-4d949c5b-968b-4fd5-be67-4cd1d1a41ce3">
        <ds:SignedInfo>
          <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
            <ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="soap"/>
          </ds:CanonicalizationMethod>
          <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
          <ds:Reference URI="#TS-09f1357c-beb4-4804-9410-76c5a06e2e48">
            <ds:Transforms>
              <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
                <ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="soap wsse"/>
              </ds:Transform>
            </ds:Transforms>
            <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
            <ds:DigestValue>HPYjNXdxIuJIWk1EArE+8PIgyWt5nAD+upwcjOSDB20=</ds:DigestValue>
          </ds:Reference>
          <ds:Reference URI="#id-27c23bc8-0c4f-4d98-b046-6e590ea9661b">
            <ds:Transforms>
              <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
                <ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="soap"/>
              </ds:Transform>
            </ds:Transforms>
            <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
            <ds:DigestValue>MJzRD4ZRMsFOxskbnfNV9BnDTCLxuLSnmZ8I4IjaxHw=</ds:DigestValue>
          </ds:Reference>
          <ds:Reference URI="#id-fb4c1fa0-e804-4169-b70e-5b55c5f9d912">
            <ds:Transforms>
              <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
                <ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="soap"/>
              </ds:Transform>
            </ds:Transforms>
            <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
            <ds:DigestValue>MIi+ovLTqYu1HqxUtmUnuhVdMmNKOpOX8vn/fKjvQFU=</ds:DigestValue>
          </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>SBYs6aikHbfsHHV04ifV/ljVTysxNLRTPU6gsOGJamWG
                    YLMPqOETjBf+NFJhPDVdolQSSHw0SD7uA/RlYkE9amRH1K+hoaUIa/PEhPgC1io/LqZdi
                    3rt+b8uRlk+CXcUKOObgf/N960F/sM6s0ArKQxg/Yx6pqWamXBXo0PH/1FvHSgwdA62s0
                    +Sli96qY0EnJPoyKIrqzskiscLXI1jCe8sesyA+xtJ0qBdFKAn2af48sVStPFv4gizC8+
                    bsCRpQ36ihUIlI8DInJ13EgoKV9/rC4PheExO7HvSNTpBFdQt+Wr9wAb3oHq4urRBdugA 6mX2xaJ8/XyZVajivvuVTw==
        </ds:SignatureValue>
        <ds:KeyInfo Id="KI-dab2ce54-b000-439a-bcc2-9b8249626a1c">
          <wsse:SecurityTokenReference xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
            xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="STR-068909fe-1a64-4cf1-bd5a-355a20b0495f">
            <wsse:Reference URI="#X509-bf881daf-371a-4d18-9502-d9f92af9a949" Valuewss="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"/>
          </wsse:SecurityTokenReference>
        </ds:KeyInfo>
      </ds:Signature>
    </wsse:Security>
    <Action xmlns="http://www.w3.org/2005/08/addressing">http://profile.security.modi.agid.org/HelloWorld/sayHi
    </Action>
    <MessageID xmlns="http://www.w3.org/2005/08/addressing"
      xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="id-fb4c1fa0-e804-4169-b70e-5b55c5f9d912">urn:uuid:46d
            a4ec1-f962-4f24-8524-48bb74b505d7
    </MessageID>
    <To xmlns="http://www.w3.org/2005/08/addressing"
      xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="id-27c23bc8-0c4f-4d98-b046-6e590ea9661b">http://local
            host:8080/security-profile/echo
    </To>
    <ReplyTo xmlns="http://www.w3.org/2005/08/addressing">
      <Address>http://www.w3.org/2005/08/addressing/anonymous
      </Address>
    </ReplyTo>
  </soap:Header>
  <soap:Body>
    <ns2:sayHi xmlns:ns2="http://profile.security.modi.agid.org/">
      <arg0>OK</arg0>
    </ns2:sayHi>
  </soap:Body>
</soap:Envelope>

GET https://api.erogatore.example/rest/service/v1/hello/echo/Ciao HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5c.vz8...

# header

{
"alg": "ES256",
"typ": "JWT",
"x5c": [
"MIICyzCCAbOgAwIBAgIEC..."
]
}

# *payload*
{
"iat": 1554382877,
"nbf": 1554382877,
"exp": 1554382879,
"iss": "https://api.fruitore.example",
"sub": "https://api.fruitore.example",
"aud": "https://api.erogatore.example/rest/service/v1/hello/echo"
}

GET https://api.erogatore.example/rest/service/v1/hello/echo/Ciao HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5c.vz8...

# *header*
{
        "alg": "ES256",
        "typ": "JWT",
        "x5c": [
                "MIICyzCCAbOgAwIBAgIEC..."
                ]
}

# *payload*
{
        "aud": "https://api.erogatore.example/rest/service/v1/hello/echo"
        "iat": 1516239022,
        "nbf": 1516239022,
        "exp": 1516239024,
        "iss": "https://api.fruitore.example",
        "sub": "https://api.fruitore.example",
        "jti": "065259e8-8696-44d1-84c5-d3ce04c2f40d"
}

Integrità¶

Di seguito le indicazioni per le tecnologie accolte dal ModI.

L’AgID assicura l’aggiornamento degli stessi per soddisfare le esigenze espresse dalle PA.

soap="http://schemas.xmlsoap.org/soap/envelope/"
wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
ds="http://www.w3.org/2000/09/xmldsig#"
ec="http://www.w3.org/2001/10/xml-exc-c14n#"

<?xml version="1.0"?>
<soap:Envelope>
  <soap:Header>
    <wsse:Security soap:mustUnderstand="1">
      <wsse:BinarySecurityToken EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary" ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x5 09-token-profile-1.0#X509v3" wsu:Id="X509-44680ddc-e35a-4374-bcbf-2b6dcba722d7">MIICyzCCAb OgAwIBAgIECxY+9TAhkiG9w...</wsse:BinarySecurityToken>
      <ds:Signature Id="SIG-f58c789e-e3d3-4ec3-9ca7-d1e9a4a90f90">
        <ds:SignedInfo>
          <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
            <ec:InclusiveNamespaces PrefixList="soap"/>
          </ds:CanonicalizationMethod>
          <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
          <ds:Reference URI="#bd-567d101-aed1-789e-81cb-5ae1c5dbef1a">
            <ds:Transforms>
              <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
                <ec:InclusiveNamespaces PrefixList="soap"/>
              </ds:Transform>
            </ds:Transforms>
            <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
            <ds:DigestValue>0cJNCJ1W8Agu66fGTXlPRyy0EUNUQ9OViFlm8qf8Ysw=* *</ds:DigestValue>
          </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>AIrDa7ukDfFJD867goC+c7K3UampxpX/Nj/...</ds:SignatureValue>
        <ds:KeyInfo Id="KI-cad9ee47-dec8-4340-8fa1-74805f7e26f8">
          <wsse:SecurityTokenReference wsu:Id="STR-e193f25f-9727-4197-b7aa-25b01c9f2ba3">
            <wsse:Reference URI="#X509-44680ddc-e35a-4374-bcbf-2b6dcba722d7" ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"/>
          </wsse:SecurityTokenReference>
        </ds:KeyInfo>
      </ds:Signature>
    </wsse:Security>
  </soap:Header>
  <soap:Body xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:id="bd-567d101-aed1-789e-81cb-5ae1c5dbef1a">
    <ns2:sayHi xmlns:ns2="http://example.profile.security.modi.agid.gov.it/">
      <arg0>Hello World!</arg0>
    </ns2:sayHi>
  </soap:Body>
</soap:Envelope>

POST https://api.erogatore.example/rest/service/v1/hello/echo/ HTTP/1.1
Accept: application/json
Agid-JWT-Signature: eyJhbGciOiJSUzI1NiIsInR5c.vz8...
Digest: SHA-256=cFfTOCesrWTLVzxn8fmHl4AcrUs40Lv5D275FmAZ96E=
Content-Type: application/json

{"testo": "Ciao mondo"}

# *header*
{
  "alg": "ES256",
  "typ": "JWT",
  "x5c": [
        "MIICyzCCAbOgAwIBAgIEC..."
  ]
}
# *payload*

{
  "aud": "https://api.erogatore.example/rest/service/v1/hello/echo"
  "iat": 1516239022,
  "nbf": 1516239022,
  "exp": 1516239024,
  "signed_headers": [
    {"digest": "SHA-256=cFfTOCesrWTLVzxn8fmHl4AcrUs40Lv5D275FmAZ96E="},
    {"content-type": "application/json"}
  ],
}