How to Publish a REST API to X-Road?

These instructions guide Security Server administrators through the process of adding and registering a new subsystem in X-Road and configuring a REST API service for it. They cover both cases where the subsystem already exists and where it needs to be created, including approval steps and expected status changes. The guide also explains how to publish a REST service with an OpenAPI 3 service description, enable it, configure its access rights, and manage TLS certificate verification. The goal is to complete the basic setup required to make the service available to other X-Road members.

1. Add a New Subsystem

1. In the Clients view, locate the Member who is publishing the service.

2. Click the Add subsystem button in that Member’s row.

Open

3. In the Add subsystem view:

   • If the subsystem already exists in the global configuration:

     • Click Select Subsystem and choose it from the list.

Open

Open

• If the subsystem does not exist:

  • Enter the Subsystem Code and Subsystem Name.

• In both cases, leave the Register subsystem checkbox selected.

4. Click the Add subsystem button.

Open

5. Confirm the registration by clicking Yes in the confirmation dialog.

Open

2. Subsystem Status and Naming Behavior

• You will be redirected back to the Clients view, and a notification “Subsystem added” will appear at the bottom of the page.

Open

• The newly added subsystem appears in the Clients list with the status “Registration in progress.”

  • If the subsystem was newly created, its name appears as “Undefined.” This is expected and will be updated once registration is complete.

  • If the subsystem already existed, the correct name will be displayed immediately.

• The registration request must be approved on the Central Server:

  • This may be done automatically or manually, depending on the Central Server’s configuration.

  • If automatic, the status typically updates to “Registered” within a few minutes. Reload the Clients view to refresh the status.

3. Configure the Service

1. Click the subsystem name to open its details.

Open

2. Go to the Services tab.

   • You may configure the service even if the subsystem registration is not yet complete.

   • However, other X-Road members cannot invoke the service until both registration and service configuration are finalized.

Open

3. Click Add REST.

Open

4. In the Add REST service view:

   • Select OpenAPI3 Description as the URL type.

   • Enter the OpenAPI3 specification URL in the URL field (e.g., https://d14r9k0rinox9f.cloudfront.net/yaml/x-road-stats.yaml).

   • Enter the Service Code (e.g., TestAPI).

5. Click Add.

Open

4. Enable and Verify the Service

• The Security Server fetches and parses the OpenAPI description.

• The service is added to the Services list but is disabled by default.

• Enable it by toggling the switch on the right side of the service row.

Open

• A notification “Service description enabled” will appear.

• Click the “>” symbol on the left to expand service details.

Open

• Click the Service Code to open the full details.

Open

5. Review and Edit the Service URL

• The Service URL is extracted from the OpenAPI servers.url field.

• This URL is where the Security Server forwards incoming requests.

• If the parsed value is incorrect, it can be manually edited.

Open

6. TLS Certificate Handling

• By default, Verify TLS certificate is enabled.

  • This means the Security Server verifies the API’s TLS certificate.

  • To enable verification, upload the API's certificate in the Internal servers → Information System TLS certificate section.

• If you prefer not to verify the TLS certificate:

  • Uncheck Verify TLS certificate.

  • In this case, no certificate upload is needed.

• Click Save to apply the configuration.

Open

7. Configure Access Rights

1. In the Access Rights section, click Add subjects.

2. Click Search without entering any criteria to list all registered subsystems.

3. Select the desired client subsystem(s) and click Add selected.

Open

4. The selected subsystems now appear under Access Rights. It has access to all the endpoints that belong to the REST API.

Open

5. Alternatively, instead of giving access to all the API endpoints, it’s possible to define access rights on an endpoint level. Open the Endpoints tab to view the list of endpoints parsed from the OpenAPI description and define access to them separately.

Open

6. Click Close to return to the Services view.

Open

8. Upload TLS Certificate (If Needed)

• If TLS verification is enabled, go to the Internal servers tab.

• In the Information System TLS certificate section, click Add to upload the API’s TLS certificate.

Open

9. Testing the Service (Optional)

• Go to the Security Server where the client subsystem is registered.

• Go to the Internal Servers tab of the client subsystem.

• Change the Connection type to HTTP (by default, the connection type is HTTPS).

Open

• Send a test request to the client Security Server. For example:

• Note: You have to use the same client and service identifiers that you used when configuring the client and service.

10. How to construct the service URL on the client Security Server (Example)?

• For example, the base path of the REST API is https://api.stats.x-road.global/v1, and the API exposes an endpoint at /instances. When invoking the endpoint directly, the full request URL is:

• However, when invoking the same endpoint over X-Road, you must replace the REST API's base path with the client Security Server's REST interface URL and append the X-Road service identifier as path parameters, following this format:

• For example, the direct API endpoint:

• Becomes the following URL when invoked over X-Road when the service identifier is TEST/GOV/1234/TestService/TestAPI:

 Related articles