REST Adapter Service component for the X-Road.
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.
More information about available features can be found here.
The fastest and easiest way to try out the application is by using the Spring Boot Maven plugin.
To do this, you need to have a working installation of Maven.
cd srcmvn spring-boot:run
After that you can access http://localhost:8080/rest-adapter-service/ to see the Rest Adapter landing page.
If customized properties are used, use the following syntax to define properties directory.
mvn spring-boot:run -Drun.jvmArguments="-DpropertiesDirectory=/my/conf"
Rest Adapter Service tries to load configuration files from the following locations,
in the following order.
If a matching directory exists, all the configuration files
need to exist in that directory, otherwise an error occurs. Configuration
directory scanning stops once the first matching directory is located.
Scanned directories:
propertiesDirectory
java -jar -DpropertiesDirectory=/my/custom/path rest-adapter-service.war
rest-adapter-service in the users home directory (for example /home/rest-adapter-service/rest-adapter-service)/etc/rest-adapter-service (Linux only)Alternative configuration locations are mostly relevant only when
starting the executable war from command line,
deploying war into a standalone container,
or running the docker image.
When Rest Adapter Service is installed from DEB- or RPM-packages,
it explicitly sets /etc/rest-adapter-service as the configuration directory.
More detailed usage examples are available in documentation.
Rest Adapter Service can be installed and run in a number of ways:
rest-adapter-service.war into a web container such as TomcatIf you had previously installed Rest Adapter with version 0.0.12 or earlier, it ran on a standalone Tomcat7 installation.
You may wish to remove the Tomcat installation, as both Tomcat and standalone Rest Adapter run on port 8080 by default and conflict with each other.
If Tomcat was installed automatically as a dependency package, it will be removed with e.g.
apt-get autoremove
Otherwise, use standard apt or yum commands to remove the tomcat7 package.
Rest Adapter Service requires java8-runtime-headless dependency.
Configure openjdk package repository, which provides that:
apt-add-repository -y ppa:openjdk-r/ppaapt-get update
Install Java 8:
apt-get install openjdk-8-jre-headless
Do not install Java 9, as Rest Adapter does not yet support it.
Install Rest Adapter Service package from the official repository with
apt-add-repository "https://artifactory.niis.org/xroad-extensions-release-deb main"curl https://artifactory.niis.org/api/gpg/key/public | apt-key add -apt-get updateapt-get install rest-adapter-service
Configure Rest Adapter Service using property files, see Rest Adapter Service principles.
Service will automatically start during boot.
Rest Adapter Service requires java8-runtime-headless dependency.
Install Java 8:
apt-get install openjdk-8-jre-headless
Do not install Java 9, as Rest Adapter does not yet support it.
Install Rest Adapter Service package from the official repository with
apt-add-repository "https://artifactory.niis.org/xroad-extensions-release-deb main"curl https://artifactory.niis.org/api/gpg/key/public | apt-key add -apt-get updateapt-get install rest-adapter-service
or from a locally built DEB-package by replacing the package name with the file path in the command above.
Configure Rest Adapter Service using property files, see Rest Adapter Service principles.
Service is enabled or disabled using system presets.
On a typical Ubuntu 16.04 system it will be enabled (and start during boots).
Install Rest Adapter Service package from the official repository with
yum-config-manager --add-repo https://artifactory.niis.org/xroad-extensions-release-rpmrpm --import https://artifactory.niis.org/api/gpg/key/public/yum install rest-adapter-service
or from a locally built RPM-package by replacing the package name with the file path in the command above.
Configure Rest Adapter Service using property files, see Rest Adapter Service principles.
Service is enabled or disabled using system presets.
On a typical RHEL 7 system it will be disabled (and not start during boots).
Enable the service (to start automatically during boots):
systemctl enable rest-adapter-service
Starting the service:
service rest-adapter-service start
Stopping the service:
service rest-adapter-service stop
To change the port, modify configuration file /etc/rest-adapter-service/application.properties
# change this to customize portserver.port=8080
On Ubuntu 16.04 and RHEL, you can follow the logs using e.g. journalctl
journalctl -fu rest-adapter-service
On Ubuntu 14.04 the same can be done using
tail -f /var/log/upstart/rest-adapter-service.log
If you do not want to install Rest Adapter as a standalone service from package repository, you can obtain the war
package from package repository, and for example deploy it to a standalone Tomcat installation.
Rest Adapter service (rest-adapter-service.war) can be downloaded from NIIS’s Maven repository:
mvn org.apache.maven.plugins:maven-dependency-plugin:2.4:get \-DremoteRepositories=https://artifactory.niis.org/xroad-maven-releases \-Dartifact=org.niis:rest-adapter-service:1.0.0:war \-Ddest=./rest-adapter-service.war
In addition, you can also build rest-adapter-service.war yourself (built war appears in target/ directory)
mvn clean install...ls -la target/rest-adapter-service-1.1.0-SNAPSHOT.war-rw-rw-r-- 1 janne janne 22459828 marra 3 16:45 target/rest-adapter-service-1.1.0-SNAPSHOT.war
To set configuration files location, you need to specify propertiesDirectory system property using a container-specific method.
You can create a docker image to run Rest Adapter inside a container, using the provided Dockerfile.
Before building the image, build the war file inside src directory
mvn clean install
If you have not built the war, building the Docker image will fail with message
Step 2 : ADD src/target/rest-adapter-service-*.war rest-adapter-service.warNo source files were specified
While you are in the project root directory, build the image using the docker build command. The -t parameter gives your image a tag, so you can run it more easily later. Don’t forget the . command, which tells the docker build command to look in the current directory for a file called Dockerfile.
docker build -t rest-adapter-service .
After building the image, you can run Rest Adapter using it.
docker run -p 8080:8080 rest-adapter-service
If customized properties are used, the host directory containing the properties files must be mounted as a data directory.
In addition, the directory containing the properties files inside the container must be set using JAVA_OPTS and propertiesDirectory property.
docker run -p 8080:8080 -v /host/dir/conf:/my/conf -e "JAVA_OPTS=-DpropertiesDirectory=/my/conf" rest-adapter-service
The build uses license-maven-plugin to generate proper license headers for the source code files.
mvn license:format generates the license headers where they are missing. More details can be found from the plugin documentation.
The Rest Adapter Service builds DEB-packages for Ubuntu using the jdeb Maven plugin.
Different profiles exist for building for Ubuntu 14.04 (Upstart) and Ubuntu 16.04 (Systemd).
Note that when building snapshot versions (i.e. pom.xml version string contains SNAPSHOT), the resulting package will contain a timestamp to make upgrading existing packages easy.
mvn -f src/pom.xml clean install -P package-trusty
The package will be generated in src/target/trusty.
mvn -f src/pom.xml clean install -P package-xenial
The package will be generated in src/target/xenial.
The Rest Adapter Service can also be packed in an RPM-package for use with RHEL (or derivatives) using the rpm-maven-plugin.
The RPM-packaging can only be run on a RHEL-platform.
mvn -f src/pom.xml clean install -P package-rpm
The package will be generated in src/target/rpm/rest-adapter-service/RPMS/noarch.
Note that when building snapshot versions (i.e. pom.xml version string contains SNAPSHOT) the resulting package will contain a timestamp to make upgrading existing packages easy.
It is possible to build RPM-packages even if running on a non-RedHat platform. A docker container can be used for the build.
# (in the directory which contains pom.xml)docker build -t rest-adapter-rpm src/main/packages/docker./build-rpm-in-docker.sh
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.
mvn clean install -Dencrypted
Running integration tests with plaintext configuration enabled:
mvn clean install -P itest
Running integration tests with encryption configuration enabled:
mvn clean install -P itest -Dencrypted
Integration tests are run on port 9898
Integration tests execute requests against several external API’s, such as http://www.hel.fi/palvelukarttaws/rest/v2/organization/.
These external API’s may for example suffer from temporary downtime, or have their data changed so that integration tests no longer pass.
To help with this problem, it is possible to mock external API’s by using Hoverfly.
(REST Adapter integration tests) ----> (Hoverfly) --?--> (external API)
Hoverfly is run in a Docker container. Before using it for integration tests, you need to build the image:
mvn docker:build -P hoverfly-record
After that, you can run integration tests so that Hoverfly simulates the external API’s. The recorded responses are stored in src/test/hoverfly/simulation.json
mvn clean install -P itest -P hoverfly-playbackormvn clean install -P itest -P hoverfly-playback -Dencrypted
(REST Adapter integration tests) ----> (Hoverfly)
To record new versions of responses into simulation.json, use profile hoverfly-record. This should be done always when integration tests are changed in such a way that
new or different responses are needed, or when the external API’s change.
mvn clean install -P itest -P hoverfly-recordormvn clean install -P itest -P hoverfly-record -Dencrypted
(REST Adapter integration tests) ----> (Hoverfly) ----> (External API)
Hoverfly playback and record tests are run so that Provider Gateway sends requests through
the Hoverfly proxy. This mode is activated using system property useHoverflyProducerProxy.
For more information look at the contribution instructions.
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.
Below is a list of people who initiated the co-operation in a Skype meeting which was held on 18th December 2014: