Publishing REST services to X-Road Security Server - Eliminating Point-to-Point Integration

The primary objective of this session is to introduce the integration of our previously developed REST APIs with the X-Road platform.

• X-Road is a system that enables enterprises to share data by routing communications across their respective information technology (IT) systems using a standardized protocol.
• Today, over one thousand organizations in Estonia, both public and private, use X-Road on a daily basis.
• X-Road has adopted open standards for the data sharing process and makes use of Application Programming Interfaces (APIs) that are widely used.
• Under the terms of the collaboration agreement between the governments of Estonia and Finland, the Nordic Institute for Interoperability Solutions (NIIS) is responsible for the maintenance of the X-Road code.
• The X-Road Fundamentals online training course is available for free, and it is the best way to get started with X-Rod. It discusses the design of the X-Road architecture as well as the functionality of the various components of X-Road.

X-Road Security Server

• Since we are going to focus on integrations and figuring out how to connect various information systems to X-Road, a workable alternative would be to use the standalone version of the Security Server rather than a full-fledged X-Road instance. This would allow us to concentrate on connecting different information systems to X-Road.
  • Thus, we can begin within a few minutes, and we won't have to worry about putting together the essential parts of X-Road. The disadvantage of a standalone Security Server is, of course, that it cannot connect with any other Security Servers; it can only communicate with itself.
  • Here's more on the X-Road and Standalone Security Server:
    • NIIS Presentation: X-Road
    • Introduction to Standalone Security Server
    • Standalone Security Server Docker image
    • X-Road Standalone Security Server Tutorial
• Let's get started with setting up the X-Road Standalone Security Server
  • We assume you have macOS. Theses instructions work similarly for Windows and Linux operating systems.
  • Docker Desktop is required in order to run the X-Road Security Server.

1. Open a new command prompt/terminal and issue this command:

docker run -p 127.0.0.1:4000:4000 -p 127.0.0.1:8080:8080 -d --name standalone --hostname ss niis/xroad-security-server-standalone:bionic-7.0.2

2. Issuing this command will launch the Standalone Security Server (SSS) service on ports 4000 and 80. The administrative interface that we will utilize is located on port 4000, however the connection to the services will be made via port 80 or 8080.
3. You can use Docker Desktop to manager the SSS container

4. Navigate to this URL https://localhost:4000 in your Firefox browser.

5. To log in, use the following credentials:
   • Username: xrd
   • Password: secret
6. If you don't have any REST services then we recommend to use our example described in the previous sections or follow these steps:
   1. Download the source code Attach:advera.zip
   2. Import it to IntelliJ IDEA
   3. Add your Postgres Database credentials in application.properties file
   4. Make sure PostgreSQL is running - If you are using PostgreSQL
   5. Run your app

spring.datasource.url= jdbc:postgresql://localhost:5432/Your_Database
spring.datasource.username= Your_Postgres_Username
spring.datasource.password= Your_Password

7. We should add our REST services as they are implemented in our previous sessions; with the following endpoints.

Method	URL	Action
POST	/api/publishers	Add a new publisher
GET	/api/publishers	Retrieve all publishers
DELETE	/api/publishers	Delete all publisher
PUT	/api/publishers/{id}	Update a publisher by :id
DELETE	/api/publishers/{id}	Delete a publisher by :id
POST	/api/publishers/{publisherId}/advs	Create/Add an advertisement for a publisher
GET	/api/publishers/{publisherId}/advs	Retrieve all advertisements of a publisher
GET	/api/advs/{advsId}/publishers	Retrieve all publishers of an advertisement
GET	/api/advs/{id}	Retrieve a specific advertisement by id
PUT	/api/advs/{id}	Update a specific advertisement by id
DELETE	/api/advs/{id}	Delete a specific advertisement by id
DELETE	/api/publishers/{publisherId}/advs/{advsId}	Delete a specific advertisement by id from a specific publisher

8. X-Road wants you to run your REST service on a different host/IP. As our REST services and the SSS are running on the same machine, then we should use ngrok to exposes local network ports to the internet via secure tunneling.
   • Note: Our Spring Boot Application aka REST services are running on http port number 8082 defined in application.properties file.
     • Open a new command prompt/terminal window and issue the following command to forward http://localhost:8082 to another URL.
       • ngrok http 8082

10. We should add our REST services to SSS.

9. Enable the service and add client.

11. That's it. It's time to test and access our endpoints (REST Services) via SSS.
    1. Open Postmane
    2. GET localhost:8080/r1/CS/ORG/1111/TestService/adv01/publishers
    3. Add header:
       1. Key: X-Road-Client
       2. Value: CS/ORG/1111/TestClient
    4. Send