Data Exchange Layer's Adapter Service
This article describes the Adapter Service of the Suomi.fi Data Exchange Layer and its implementation methods.
The Adapter Service is a component located between the X-Road Security Server and the connected system that adapts the services provided by the connected system to the X-Road communication protocol format.
SOAP
Connecting SOAP-based systems to the Data Exchange Layer is simple. At its simplest, connecting the system to the Data Exchange Layer means setting up a Security Server and implementing an Adapter Service to add the required SOAP header information. In addition, the Adapter Service must provide interface descriptions for the services to be connected (WSDL).
REST
An Adapter Service is no longer needed after version 6.21.0, as X-Road supports REST natively.
X-Road serves as a data transmission layer between the systems connected to it. It provides a secure and standards-compliant way of publishing and utilising electronic services and interfaces. Services provided by X-Road systems are published as SOAP interfaces. Service requests and response messages between systems are transmitted as encrypted SOAP messages between Security Servers.
Joining the Data Exchange Layer requires that the system to be connected is able to send and receive SOAP messages in the format required by X-Road. In practice this means that the SOAP messages must contain certain heading data as defined by the X-Road data transfer protocol. The body of the SOAP message must contain query and response parameters as specified by X-Road. In addition, the Adapter Service must provide interface descriptions for the services to be connected (WSDL).
The Adapter Service adds header data and performs other necessary measures. This service can be implemented either directly in the connected system or in a separate Adapter Service between the system and the Security Server. X-Road requires that the interface descriptions (WSDL) of the services published through it are available through the Adapter Service. This only applies to systems providing information to the Data Exchange Layer. Systems that only utilise data do not need to offer their interface descriptions to X-Road.
Figure 1 shows the implementation of the Adapter Service as a separate service.
The Adapter Service is not a prefabricated component that comes with the X-Road solution; it must be implemented separately for each system to be connected. The tasks of the Adapter Service are:
- Converting messages from the attached system to the X-Road communication protocol format
- Providing Security Servers with interface descriptions (WSDL) of services connected to X-Road.
Practical implementation
The options for implementing the Adapter Service are shown in Figure 2.
- Directly as part of the connected system
- As a separate software component to be placed on the same server platform as the attached system
- As a separate software component that is placed on its own server platform.
The Adapter Service does not necessarily need to be a new software component developed for the Data Exchange Layer. It can also be a software package that implements the message conversions required by X-Road, such as an Enterprise Service Bus (ESB) application. Option 3 describes the use of the ESB application or other firmware in the implementation of the Adapter Service.
Depending on how the Adapter Service is implemented, the same Adapter Service can be used by several information systems connected to X-Road. In practice, an Adapter Service should be designed in a way that allows it to be used in the X-Road implementation of several systems. The SOAP header information required by X-Road has the same structure regardless of the system to be connected, so we do not recommend that you implement the data processing functionality separately for each system to be connected. Implementing a versatile Adapter Service will significantly reduce both maintenance and future work associated with connecting new systems.
Useful information
The following is a collection of materials related to the implementation of the Adapter Service: