X-Road REST Adapter Service

REST Adapter Service provides REST support to X-Road data exchange layer solution. REST Adapter Service sits between X-Road Security Server and a REST client or service (diagram). The component implements X-Road v4.0 SOAP profile and it's compatible with X-Road v6.4 and above.

REST Adapter Service has two parts: Consumer Gateway and Provider Gateway. It is possible to use either only Consumer Gateway, only Provider Gateway, or both.

• (A) using both Consumer and Provider Gateways
  • when both the client and the server are REST/JSON, but the messages need to go through X-Road
  • when end to end encryption is needed
• (B) using only Consumer Gateway
  • when the service is SOAP/XML, but a client needs to access it through REST/JSON
• (C) using only Provider Gateway
  • when a REST/JSON service needs to be published in X-Road for SOAP/XML clients

More information about available features can be found here.

Try It Out

The fastest and easiest way to try out the application is by using the Spring Boot Gradle plugin. To do this, you need to have a working installation of Gradle.

cd adapter
./gradlew bootRun

After that you can access http://localhost:8080/rest-adapter-service/ to see the Rest Adapter landing page.

If customized location for ConsumerGateway and ProviderGateway properties are used, use the following syntax to define

./gradlew bootRun --PpropertiesDirectory=/my/conf

When using default properties file location (classpath) you can pass -Pencrypted to use the encrypted-profiles properties file. If that property is not provided, plaintext-profile will be used.

./gradlew bootRun --Pencryped

Configuring REST Adapter Service

Please refert to the Configuring REST Adapter Service documentation for more information on how to configure the service.

Installing Rest Adapter Service

Build or download the jar file. You need to have Java 21 installed. Run

java -jar rest-adapter-service-x.x.x.jar

Changing the port

To change the port, modify configuration file /etc/rest-adapter-service/application.properties

# change this to customize port
server.port=8080

Building and packaging

Source code license headers

The build uses license-gradle-plugin to generate proper license headers for the source code files.

./gradlew licenseMain generates the license headers where they are missing. More details can be found from the plugin documentation.

Building docker container

From /adapter run

# in the directory where the Dockerfile is located
docker build -t rest-adapter-service .

Optionally you can pass --build-arg PROPS_DIR=./customProperties to use custom properties directory including the configuration for Provider and Consumer Gateways.

docker build -t rest-adapter-service --build-arg PROPS_DIR=./customProperties .

Then the container can be run with the command below. The port can be changed by passing the -p option.

docker run -d -p 8080:8080 rest-adapter-service

Encryption of Message Content

Starting from version 0.0.10 Rest Adapter Service supports encryption/decryption of message content. More information and instructions for configuration can be found in the documentation.

By default plaintext configuration is enabled. The software can be built with encryption configuration enabled using the command below. This setting only affects the default configuration bundled inside the war file, and the integration tests. External configuration, in /etc/rest-adapter-service or elsewhere, is not affected.

./gradlew clean build -Pencrypted

Running integration tests with plaintext configuration enabled:

./gradlew clean intTest

Running integration tests with encryption configuration enabled:

./gradlew clean intTest -Pencrypted

Integration tests are run on port 9898

Mocking external API's for integration tests

Integration tests execute requests against several external API's, such as http://www.hel.fi/palvelukarttaws/rest/v4/organization/. These external API's may for example suffer from temporary downtime, or have their data changed so that integration tests no longer pass.

Additional documentation

• Requirements
• Setting up development environment
• Setting up SSL on Tomcat
• Import a certificate as a trusted certificate
• Encryption
• Rest Adapter Service principles
• Obtaining WAR file from package repository
• Examples
  • Configuring Rest Adapter Service provider
  • CRUD API configuration

Links to material

• Data exchange layer X-Road
• X-Road community
• Nordic Institute for Interoperability Solutions (NIIS)
• XRd4J - Java library for X-Road v6

Want to contribute?

For more information look at the contribution instructions.

Credits

The development of REST Adapter Service started as a joint effort between Finland and Estonia in December 2014. Since then the component has been developed by different people and organizations.

• REST Gateway was originally developed by the people listed below (https://github.com/educloudalliance/xroad-rest-gateway) during 2014-2017.
• The name of the component was changed to REST Adapter Service (https://github.com/vrk-kpa/REST-adapter-service) and it was maintained and further developed by the Finnish Population Register Centre (VRK) during 06/2017-05/2018.
• In June 2018 it was agreed that Nordic Institute for Interoperability Solutions (NIIS) takes maintenance responsibility.

Below is a list of people who initiated the co-operation in a Skype meeting which was held on 18th December 2014:

• Andres Kütt (Estonian Information System Authority, RIA, Estonia)
• Alar Jõeste (Cybernetica, Estonia)
• Margus Freudenthal (Cybernetica, Estonia)
• Petteri Kivimäki (Population Register Centre, Finland)
• Jarkko Moilanen (Ministry of Education and Culture, Finland)