Unmaintained repository. Development moved to: https://github.com/nordic-institute/REST-adapter-service
REST-adapter-service is now actively developed by the Nordic Institute for Interoperability Solutions (NIIS) The original REST-adapter-service codebase here will be kept for archive purposes.
This repository will be the home of REST/JSON support solutions for X-Road. The mandate for joint development is based on the MoU which was signed by Katainen and Ansip. The development and the repository are shared between Estonia and Finland. Below is a list of people who initiated the co-operation in a Skype meeting which was held 18.12.2014.
People involved in initiation of co-operation:
- 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)
X-Road was launched in 2001. The data exchange layer X-Road is a technical and organizational environment, which enables secure Internet-based data exchange between the state’s information systems.
X-Road is not only a technical solution, the exchange of data with the databases belonging to the state information system and between the databases belonging to the state information system shall be carried out through the data exchange layer of the state information system. X-Road allows institutions/people to securely exchange data as well as to ensure people’s access to the data maintained and processed in state databases.
Public and private sector enterprises and institutions can connect their information system with X-Road. This enables them to use X-Road services in their own electronic environment or offer their e-services via X-Road. Joining X-Road enables institutions to save resources, since the data exchange layer already exists. This makes data exchange more effective both inside the state institutions as well as regarding the communication between a citizen and the state.
In this repository you will find (2015) Proof of Concept level code for a service that will enable REST support in X-Road version 6. The solution will not be a part of the Security Server, but more like a "REST Proxy". The solution could be included to the Security Server in the future, but that remains to be seen. No plans for that have been made.
First aim is to get first practical REST API integrated to X-Road, document the process and open the code. We also need to test and evaluate the toolchain for example for WSDL-RAML conversions and other things.
In parallel with the technical development we will collect more use cases from Finland about REST/JSON APIs that need to be integrated with X-Road. Aim is not to make automated solution which covers 100% of cases. We will cheer loudly if 80% coverage is achieved.
For more information look at the contribution instructions.
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 src
mvn 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:
- The directory specified by the system property
propertiesDirectoryjava -jar -DpropertiesDirectory=/my/custom/path rest-adapter-service.war - The directory
rest-adapter-servicein the users home directory (for example/home/rest-adapter-service/rest-adapter-service) - The directory
/etc/rest-adapter-service(Linux only) - As a fallback, the default configuration shipped with the WAR (classpath)
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:
- Using package manager to install DEB- or RPM-packages
- Deploying
rest-adapter-service.warinto a web container such as Tomcat - Using Docker to run Rest Adapter Service
If 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 autoremoveOtherwise, 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/ppa
apt-get updateInstall Java 8:
apt-get install openjdk-8-jre-headlessDo 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 -y "deb http://www.nic.funet.fi/pub/csc/x-road/rest-adapter-service/0.0.13/trusty stable main"
curl http://www.nic.funet.fi/pub/csc/x-road/client/ubuntu-dev-current/packages/dists/stable/palveluvayla@gofore.com.asc | sudo apt-key add -
apt-get update
apt-get install rest-adapter-serviceConfigure 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-headlessDo 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 -y "deb http://www.nic.funet.fi/pub/csc/x-road/rest-adapter-service/0.0.13/trusty stable main"
curl http://www.nic.funet.fi/pub/csc/x-road/client/ubuntu-dev-current/packages/dists/stable/palveluvayla@gofore.com.asc | sudo apt-key add -
apt-get update
apt-get install rest-adapter-serviceor 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
sudo yum-config-manager --add-repo http://www.nic.funet.fi/pub/csc/x-road/rest-adapter-service/0.0.13/rhel/7/stable
rpm --import http://www.nic.funet.fi/pub/csc/x-road/client/rhel7-dev-current/palveluvayla-sign.gpg
yum install rest-adapter-serviceor 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-serviceStarting the service:
service rest-adapter-service startStopping the service:
service rest-adapter-service stopTo change the port, modify configuration file /etc/rest-adapter-service/application.properties
# change this to customize port
server.port=8080On Ubuntu 16.04 and RHEL, you can follow the logs using e.g. journalctl
journalctl -fu rest-adapter-serviceOn Ubuntu 14.04 the same can be done using
tail -f /var/log/upstart/rest-adapter-service.logYou can either build rest-adapter-service.war yourself (built war appears in target/ directory)
mvn clean install
...
ls -la target/rest-adapter-service-0.0.12-SNAPSHOT.war
-rw-rw-r-- 1 janne janne 22459828 marra 3 16:45 target/rest-adapter-service-0.0.12-SNAPSHOT.waror extract war file from a DEB- or an RPM-package which has been downloaded from the packet repository. For detailed instructions, see this page.
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.war
No 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.shStarting 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