1.1 Background¶

The National Recovery and Resilience Plan (PNRR) has set as one of its objectives the revitalization of the economic sector of Tourism. Tourism in Italy, in fact, represents an important source of competitive advantage for the entire country, with 13% of GDP in 2017 (Bank of Italy) and counting over 500 thousand supply chain enterprises in 2019 with over 1.9 million employees (ISTAT). Tourism-related consumption in 2018 was around €84 billion (ISNART). ISTAT data reported, before the epidemic, arrivals - national and international - of around 131 million and presences of around 436 million (ISTAT).

Concerning Measure 4. «Tourism 4.0», Investment 4.1 - «Tourism Digital Hub» (TDH) is aimed at creating a dedicated web platform, which allows the connection of the entire tourism ecosystem to enhance, integrate and promote its offer.

The expected outcomes of TDH are:

• Increasing flows, destinations and spending, by increasing the quality of the offer and the related exposure of the Italian Points of Interest for Tourism (POI);
• Enhancing the existing framework of digital assets - e.g., regional portals - without any overlapping, while also offering cost saving solutions;
• Strengthening the role of TDH’s digital assets, defining them as real institutional reference points for searching for POI-related information with respect to an audience of national and international tourists;
• Involving the entire Italian tourism system through an open-source approach that collects input and generates output for all stakeholders;
• Retaining users (and therefore potential tourists) through tailored proposals based on their needs and preferences, offering a bespoke portal experience;
• Favoring the development of a platform that provides timely and correct information on POIs across Italy, and whose data will be used by external tracking platforms such as Google My Business, Bing Places, Apple Maps and so on - thus bringing an additional benefit in terms of visibility on the most common search engines.

The Ministry of Tourism, assisted by ENIT - the National Agency for Tourism, is in charge of coordinating the entire Italian tourism ecosystem, promoting, in a joint approach, the re-launch of tourism through a comprehensive and mixed offer of information and services, facing the continuous changes in national and international market demand.

The purpose of the TDH initiative is the re-launch of Italia.it, enriched with new internally produced content and in partnership with Regions and Autonomous Provinces, but also through integrations with partners in Tourism. In detail, for each topic discussed, the website will offer content with a triple relevance:

• Content of Interest: editorial content, which enables the TDH to infer the Person’s interest when reading it. It enables the description of one or more destinations, one or more offers and/or any type of event related to the tourist experience in our territory (e.g.: an editorial article that talks about the Palio of Siena, if read by the tourist, suggests interest for Siena and its historical pageants);
• Destination: local attraction related to a point of interest (x, y coordinates) or to a geographical area («geometry») that persists in the medium-long term (e.g., Colosseum, Trevi Fountain, the city of Rome, etc.);
• Offer: a touristic item that can be consumed/booked/seen for a fee (e.g., a hotel room, a museum entry).

TDH also aims at making the tourist market demand towards Italy profitably meeting the related Italian offer (provided by different actors), by connecting the individual’s (tourist) interests, destinations and offer before, during and after the tourism experience, creating value for all stakeholders involved.

Within the TDH, the design and implementation of an Integration Platform - Full Life Cycle API Manager is foreseen to support interoperability between applications and services both external and internal to the TDH:

• external services: second-party data (e.g., regions), third-party data (e.g., private and public organizations complementary to the national government system), geographical data;
• internal services: integration with internal TDH applications that are related to specific modules (e.g., CRM).

To achieve its goal of involving the whole Italian tourism system, the Integration Platform and API Manager ensures the IT and information coordination of data between Administrations (central, regional and local), Organizations and Third-Party Companies with the TDH Digital Ecosystem. A standard communication protocol between the TDH and the external world, defined TDH022, has also been adopted.

Accordingly, the TDH022 acts as a Digital Standard at National level, in charge of exchanging both «open» (open data) and «closed» (private data) data and contents among the participants, also being the integration interface between the TDH and the Industry Professionals interested in joining the Ecosystem and operating in the Italian domestic area.

Figure 1 - TDH ecosystem and external connection through TDH022 shows the Tourism Digital Hub and interconnection strategy.

Figure 1 - TDH ecosystem and external connection through TDH022

The interaction procedures with TDH Ecosystem allow both the use of digital services available in it and the development/supply of new ones (open or closed) making them available to Ecosystem members. In this sense, the interactions contemplate that the operators (public and private) adhering to the TDH022 can operate, depending on the case, as follows

• service provider, in case they provide any services and functionalities to TDH;
• service users, if they use digital services provided by third parties within the Ecosystem.

1.2 Purpose of the document¶

This document acts as a framework for the Interoperability the Ministry of Tourism plans to adopt with Institutional and Private Stakeholders, for the exchange of information, data and services with the TDH.

This document provides the Guidelines which are further detailed in the related Operative Documents.

These Guidelines define standards and technologies that Public Administrations will have to comply with to make their information systems interoperable, in order to allow the information and data exchange between Administrations (central, regional and local), Public Entities and Third-Party Companies with the TDH Digital Ecosystem, henceforth «Ecosystem» or «TDH», through the TDH022.

Guidelines in this document guarantee consistency with:

• technological evolution;
• compliance with the European Interoperability Framework (EIF) guidelines;
• adequacy to the information/technical needs of administrations and their users;
• adoption by the Public Authorities and Private Partners concerned;
• uniform ontologies and taxonomies for content classification and organization;
• adequacy to the necessary security levels.

This document will be constantly updated by the Ministry of Tourism according to technological and/or regulatory developments that may arise.

These Guidelines are also compliant with the recommendations issued by AgID, ref. document «Guidelines on the technical interoperability of Public Administrations» [letter b) paragraph 3-bis article 73 of Legislative Decree no. 82 of 7 March 2005] helping in defining an interoperability model between tourism operators, by focusing on processes, technologies and their methods of use, in order to ensure the exchange of data and contents with the TDH using the TDH022 standard. Furthermore, the Interaction Environments within the Ecosystem are defined.

Lastly, Guidelines address the technical interoperability level and support the standardization initiatives endorsed by the European Commission (ref. Doc. European Interoperability Framework - EIF).

2.1 Structure of document¶

These Guidelines provide a general overview and are linked to Operative Documents (DO) Figure 2 - Structure of the Guidelines and Operational Documents - to which are linked for details on technological standards and their methods of use to benefit from and / or provide digital data and / or services through third party systems to and from the TDH:

To ensure constant alignment with technological evolutions, the updating of the DO is carried out by the operators in charge in compliance with the timing and methods chosen for their updating.

Figure 2 – Guidelines and Operative Documents Structure

2.2 Normative requirements [1]¶

The reference regulatory acts of this document are listed below:

2.3 Terms and definitions [1]¶

3.1 Interactions [1]¶

The scope of application of these Guidelines, in line with the Interoperability Model of Italian Public Administrations (ModI: Model created by AgID which enables the collaboration between Public Administrations and between these and third parties by means of technological solutions that ensure interaction and exchange of information without constraints on implementations, avoiding ad hoc integrations), includes the three types of interactions envisaged in the EIF that involve Public Administrations, Citizens and Companies.

The ways of interaction with the TDH Ecosystem will allow both the use of (open) digital services available inside it and the development / delivery of new ones (open or closed) by making them available to those participating in the Ecosystem. In this sense, the interactions provide that the operators (public and private) adhering to the TDH022 can perform the function of service provider and user of the services, as previously described. In this sense it is possible for a tour operator to perform one or both functions.

The users can use the digital services made available by the service providers, who have evidence of their use through specific control mechanisms such as:

• a software solution that includes a control mechanism operated by a specific operator in the back end of the Platform (user agent / human);
• an automatic application system (server / machine), also for the purpose of defining new value-added services (connection via API).

3.2 Application Programming Interface (API)¶

In the context of communication between external systems and TDH, two modalities of interchange are defined:

• RESTful web API (recommended),
• Web Services on standard SOAP, whenever the systems do not entail the use of RESTful web API.

API (Application Programming Interface) means “a set of protocols / functionalities / definitions through which it is possible to create integrated application systems; in this sense, the API is conceived as a «black box», namely a callable function for which it is only necessary to know its interface, without the need to know any implementation details [1]”.

Web APIs are APIs that can be called up from the Web (mainly based on HTTP protocol), whose goal is to obtain a high level of abstraction that mediates between the logic layer and the clients requiring its service. Web APIs are mainly of the REST type or of the SOAP type.

The data format for the SOAP Web API (or SOAP Web Service) is XML, while for the RESTful web API it is possible to leverage the formats provided by the HTTP protocol as defined by the W3C.

In the context of the RESTful web API, reference is made to the REST architecture, according to the Richardson maturity model [2]; in this sense, the RESTful model is compliant with level 3 of maturity - Hypermedia Controls.

The Guidelines identify the ways in which developers / adherents to TDH022 implement their APIs, as basic technological elements through which it is possible to establish the interconnection with the TDH and the use of services and / or contents by end users.

3.3 Quality of Services (QoS) [1]¶

Quality of Services (QoS) refers to the API non-functional description, or the ability of the latter to meet the expectations of users.

Ensuring QoS on the Internet for interoperability purposes is a critical challenge due to the dynamic and constantly evolving nature of the technological environment. Changes in traffic patterns, the presence of critical transactions, the effects of network problems, the performance of network protocols and standards require an accurate and precise definition of the QoS offered by an API.

The key elements supporting QoS can be summarized as follows:

The subjects (public or private) adhering to the TDH who make data and content available, must take all the necessary steps to guarantee the QoS requirements required by the case of use. This also includes the use of good practices, for example, to ensure performance and scalability, as well as the implementation of mechanisms that ensure the greatest possible bandwidth savings.

3.4 Service Level Agreement (SLA) [1]¶

The integration may involve numerous TDH adherents who expose their APIs. To align on QoS, providers and users of APIs use what are known as Service Level Agreements (SLAs), or service level agreements. An SLA consists of the following elements:

SLAs can be static or dynamic. In dynamic SLAs, the SLOs (with associated SLI) vary over time and the validity periods define the validity intervals of the latter (e.g., during working hours the SLOs can be different from those set during the night). The measurement of QoS levels within an SLA requires the tracking of operations carried out in a multi-domain infrastructure context (geographical, technological and applicational).

3.5 Interoperability domain [1]¶

In the context of these Guidelines, the interoperability domain means a specific context in which several Administrations and / or Private entities need to exchange data and / or integrate their processes to follow up on the regulatory provisions.

Each interoperability domain is characterized by:

• the participating subjects, the Administrations and Institutions (including the Ministry of Tourism and ENIT) and any private subjects (citizens and businesses);
• the IT systems of the participating parties that exchange data and / or integrate their own processes;
• the set of APIs implemented to ensure interactions between the IT systems of the participating parties;
• the security criteria that the single APIs provide to ensure transactions between participating parties that comply with the standard.

3.6 Logging [1]¶

Logging plays a vital role in API design and development. Modern middleware platforms, in addition to integrating internal logging mechanisms, can connect to external APIs that allow the collection (log collection), research and production of analytics, useful for the identification of problems and the monitoring of the system and QoS. The use of log collectors allows to centralize not only the logs related to the use of the API, but also those of any other digital services and network components (e.g., Proxies and application-gateways). For non-repudiation purposes, the application messages can be stored together with the digital signature and archived in compliance with the regulations on conservation and privacy. The provider must document in detail the format and methods of information tracking, consulting and retrieving.

Figure 3 - Explanatory diagram of TDH logging process

As part of the TDH022 interoperability, the provider will not track confidential information such as passwords, private keys or authentication tokens in the logs; in addition, it must trace an event for each request containing at least the following minimum parameters:

• Timestamp of the request;
• identification of the user and of the requested operation;
• type of call;
• outcome of the call;
• where applicable, the identification of the Consumer of the API Service or other person operating the request communicated by the User - who will provide for the coding and anonymization, where necessary;
• a unique identifier of the request, useful for any correlations.

3.7 Interoperability patterns and profiles [1]¶

Guidelines identify:

The interoperability patterns are divided into:

The Patterns and Interoperability Profiles identified in the Operating Documents of the TDH022 Guidelines are used by the Administrations in the implementation of their APIs; furthermore, the Administrations select the Patterns and / or the Interoperability Profiles based on the specific needs of the interoperability domain in which they participate.

3.8 API Catalog [1]¶

The Guidelines define the Catalog of API TDH022 (in brief, Catalog) as a single and centralized component, which ensures to the parties involved in the delivery and use relationship the knowledge of the available APIs, and for the latter, the declared service levels.

The presence of the Catalog is functional to:

• facilitate the interoperability between administrations and interested private parties;
• contain government spending by reducing API replication;
• ensure the declaration of the SLOs by the Provider on the single published APIs;
• express, where present, the commitments between Providers and Users relating to the use of APIs (SLA).

The Catalog, without prejudice to the common principles that will be issued by the Ministry of Tourism, in order to standardize the technologies used at national level, considers:

• Specificity of the different areas within which the Ministry of Tourism operates through the determination of thematic classes of the contents in the Catalog, thus providing aggregations of APIs based on different taxonomies. This choice is further justified by the opportunity to share common methodologies for the purposes of design and development within a common ecosystem (TDH).
• Need to ensure the governance of the Catalog, as a prerequisite for guaranteeing a univocal and shared semantics, to avoid redundancies and / or overlaps in terms of competences and contents (de-duplication).
• Need to ensure a formal description of the APIs which, using the Interface Description Language (IDL) indicated, allows to describe the APIs regardless of the programming language adopted by the Provider and Users.

3.9 Model Governance [1]¶

The Ministry of Tourism is responsible for governance activities with the aim of defining, sharing and ensuring the continuous updating of the following aspects:

• the set of technologies that enable interoperability between the members of the Ecosystem;
• the Interoperability patterns (interaction and safety);
• the Interoperability profiles;
• the set of Taxonomies and Ontologies.

The relationship between Users and Providers is made explicit through the Catalog.

Adhesion to the TDH takes place by signing the relevant Agreement, which governs the roles, responsibilities and obligations of the Parties. Without prejudice to the uses permitted to MiTur within the scope of the TDH, the use of the API of a Provider by a User in contexts and for purposes unrelated to the TDH is subject to a further Authorization by the Provider itself, which it will be managed digitally with a specific procedure on the TDH.

Providers must describe their e-services by classifying the information exchanged (where possible by linking it to controlled vocabularies and semantic concepts defined at national and / or international level) and apply labels that identify the category.

A Provider can delegate the registration of e-services within the Catalog to another subject (Regional and / or Local Administrations, Entities or Third Parties) in relation to specific territorial contexts and / or thematic areas.

The API Catalog allows Public and Private entities to know the e-services available and their delivery and use methods within the ecosystem.

The Ministry of Tourism has the role of:

• acknowledge the interoperability needs of Regional and / or Local Administrations, Entities or Third Parties, abstract them and eventually formalize new patterns and / or profiles of interoperability;
• coordinate the process of defining the interoperability profiles and patterns;
• make the Catalog available, through a single access interface to allow all interested parties, public and private, to know the available e-services;
• request the adoption of Interoperability Patterns and Profiles for the implementation of APIs as a condition for registering with the Catalog, as well as continuously checking compliance with the requirements for registering with the Catalog itself.

4.1 Software System Platform¶

For interoperability with Tourism Digital Hub, it is recommended that Hosts (e.g., Authorities, Regions) use an application that allows to manage APIs (invoke/expose) and enables to consult and monitor them, guaranteeing their operational management:

• API Manager: useful for setting access rules to your APIs and managing them;
• API Gateway: a tool that manages APIs, interposing itself between a client and a series of back-end services; in essence, an API Gateway acts as a reverse proxy, accepting all API calls, and where authorizations and authentications are involved, it has the task of accepting only authorized/authenticated calls. It is also responsible for aggregating the various services requested, returning an appropriate result;
• Integration Platform: tool that deals with the mediation between services in order to realize «loose-coupled» [1] (low dependency) models between providers and service users, thanks to the introduction of a broker middleware that deals with providing:
  • protocol and data format conversions;
  • policy in the interaction between providers and users (e.g., auditing, logging and security monitoring);
  • Logic for the invocation and forwarding of calls to services (dispatching).

It is also recommended to include the Orchestration component, understood as the coordinated composition and execution of APIs that can be organized into three macro-categories:

• Interface layer: level of specific relevance of the Gateway, where the interfaces towards the clients that consume the service are realized;
• Application & Orchestration Services: service level focused on the service logic domain, business process orchestration and abstracted from enterprise integration issues at the back-end level;
• System services: services that operate at the integration level of individual back-end applications (e.g., Database, Host, Cloud SaaS).

In addition to this, it is necessary to provide «end to end» Monitoring and Alerting functions of the API integration flows developed for the purpose of TDH022 interoperability.

Figure 4 – Diagram explaining the API Gateway application platform

4.2 Minimum requirements for TDH interconnection¶

In order to establish a connection between Operators and TDH, it is recommended that parties wanting to interconnect with it equip themselves with a technological infrastructure that allows them to exchange/receive information and content, using an encrypted, authenticated and authorized method.

In particular, for the Regions it is foreseen the sharing and/or transmission of digital content (articles, images, videos etc…) and information referring to POI (Points of Interest), Destinations, Interests and Offers. Therefore, it is recommended that the Regions, if they are not already so, equip themselves with specific tools capable of managing the storage and, when necessary, the transmission of such content (e.g., CMS).

In general, it is recommended that Operators interested in interconnecting with the TDH have the appropriate application tools for the bidirectional exchange of information with relative real time updating where possible.

It is therefore possible to make the bidirectional TDH/Operator connection via API by means of:

• API with content link: in order to provide digital content shared by operators such as images, videos, articles, etc., APIs will be displayed with links to recall the resource (content) present in the Operator’s CMS and presented by TDH;
• API with content: in order to directly enjoy digital content shared by the above operators that is transmitted directly to the end user by the DMS;
• API for transmitting and/or receiving information: for the purpose of information exchange between TDH and Regions/Operators.

Figure 5 – Explanatory diagram of the TDH/Region’s interconnection through different APIs

5.1 Web Service SOAP (simple object access protocol)¶

SOAP is a protocol used for message interchange that, although it can rely on several network protocols (e.g., JMS), is standardized for the http protocol only (W3C).

SOAP, which has seen its success with the rise of service-based architectures is based on XML with a header-body structure, divided into the following sections:

• Soap-Header (optional): this section contains data that are not related to the content of the information to be exchanged, but to the metadata related to the logging, routing, security and orchestration processes;
• Soap-Body (mandatory): this section contains data related to the information to be transmitted.

The interface Descriptor is based on the WSDL (Web Service Description Language) metalanguage and, in this sense, in order to allow systems to communicate with each other by means of SOAP, it is necessary that the same systems can exchange the WSDL.

The SOAP call, at last, uses only the POST method of http, with the possibility to send attachments to the request.

5.2 API web RESTful (Representational State Transfer)¶

Before introducing RESTful Web APIs specifically, a preliminary discussion about «REST» is needed; specifically, REST is not a protocol, but an architectural style, that is, it represents an abstraction of the components of an architecture within a distributed hypermedia system. The basic principles of this architectural style are:

• Client-Server (the separation of concerns (SoC) paradigm is used): at design level each system must be designed as a module with a specific task; in substance, the Client can only invoke an API made available by a Server which takes care of executing the requested activity, or rejecting it, returning a response message to the Client. The management of exceptions/rejections is delegated to the Client;
• Stateless: communication between a Client and a Server must be stateless between requests; this means that each request originating from the Client must have the set of information needed to allow the Server to understand the request. So, all the necessary data is returned to the Client at the end of each request;
• Cacheable: in this type of architecture the concept of «cache constraint» exists, that is the obligation to label the answers as «cacheable» or not. This allows one of the actors that interpose themselves between Client (including) and Server to store the response in the cache, and thus improve network performance;
• Uniform Interface: in order to have an efficient caching strategy in a network, there is the concept of «constraint of uniformity of the data access interface», that is the obligation that the components involved in the communication use a uniform interface; this constraint has some declinations, such as the concept of «resource»: every information is represented, therefore, as a «resource». Although a resource may change over time, the semantics of its mapping must remain constant: in essence, a resource must be uniquely identified (URI) over time. Another feature is how the resource can be represented in different ways (JSON, GeoJSON, XML, JPG) and this is made possible through the definition of data, metadata and control data. Control data can define the purpose of a message, for example how to manage the cache of a response. Last declination is the one related to the link between resources according to the HATEOS principle (Hypermedia As The Engine Of Application State);
• Layered System: the main concept in this case is that a REST architecture is represented through multiple architectural layers, independent of each other, with specific purposes (e.g., security, balancing, …);
• Code on demand (optional): a REST-based implementation can extend client functionality by executing code (e.g., scripts or applets).

RESTful web APIs are based on HTTP protocol, from which they inherit all the properties, such as the format of the transported data, defined by the «content-type», or the error codes returned by the server (e.g., 400, 500), and the methods (e.g., Get to retrieve data, Post to create resources, Delete to delete resources, …).

Figure 6 - REST and SOAP compared

6.1 Ontologies: An introduction¶

An ontology is a formal representation of knowledge in a specific domain, which can organize, model and manage information and knowledge, subsequently sharing and reusing it in one or more domains. The ontology also allows the definition of a common vocabulary, clarifying the meaning and correlation between terms and how they relate to each other, allowing semantic modelling combined with domain knowledge.

Building an ontology within an organization enables the establishing of standards at an organizational level, creating and improving links between different domains, thus leading to greater transparency and better interpretation of data.

6.2 The role of Ontologies in the organizational ecosystem¶

The role of the ontology is to play the role of the «common driver» between existing and potential data sources inside the Ecosystem, and in particular in TDH. The main objective of ontology development is to identify the smallest number of entities needed to ensure a high level of data inter-operability.

Building an ontology leads mainly to two advantages:

• Stakeholders agree on common vocabulary used to describe components,
• Different systems, databases and applications, can communicate without having to connect to each other.

These two features enable the development of new information systems within TDH022 through faster and more efficient data exchange, facilitating integration between data from different sources.

6.3 Ontology development process¶

7.1 Participation to TDH Ecosystem – The contractual model¶

The procedures for joining the TDH Digital Ecosystem involve the signing of conventions and contracts that govern the operations of the Second and Third Parties, relating to the exchange of data and contents both with subjects within the aforementioned Ecosystem and externally such as, for example, tourists who will use the contents displayed on the Tourism Digital Hub.

Given the continuous evolution of the digital world and the need to better protect all categories of data, in compliance with the obligations established by the European and national legislator, for the purposes of defining the contractual model for joining the TDH Ecosystem, we proceeded to use a methodological approach based on the following elements:

7.2 The methodological approach of the contractual model¶

The methodological approach for enrolling in the Ecosystem takes into consideration the particular elements that concern the individual categories of actors, institutional and non-institutional, data and information flows that will be part of the operational model of the Ecosystem itself. The approach is therefore modular and aims to minimize the administrative burden on the parties involved, in view of the role they actually play in the Ecosystem. As the complexity and variety of the exchanged data and flows increase, the model responds with the definition of further technical annexes to the main contractual model, which regulate the most complex cases of interaction, namely those enabling the design and implementation of new services by Second and Third Parties. The methodological approach also includes a support to the adherent parts of procedural, functional and technical nature.

7.3 The Enrollment Process to the TDH Ecosystem¶

Enrollment of the Ecosystem takes place through a specific digitized process which involves the participation of the parties involved. In particular, the member must proceed with the signing of the contractual model and, if applicable to the specific case, of the related attachments. The subscription presupposes, as already mentioned, the recognition of the digital identity of the subscribers, in the forms governed by the current regulations. The enrollment process will be valid for 24 months, after which the system will communicate to the adherents the need to re-sign the contractual model. Any adjustments to the model and / or its annexes, for example resulting from changes to the reference regulatory framework, will be communicated to the Parties.