Central Server API

This API can be used to add new X-Road members and subsystems directly to X-Road Central Server without web admin interface. API is compatible with X-Road versions 7.3+ and is using an official management API for Central Server to save data.

The advantage of using this API in favor of official API is compatibility with previous versions of CS API, possibility to use TLS certificates for authentication and limiting access to Central Server API to only required functionality. For example when using official management API client application would be able not only to add new members and clients but additionally to delete them and perform various other actions in Central Server.

For Central Server versions prior to 7.3 use older version of CS API.

NB! Make sure your API is not accessible from public internet, and is properly secured in your internal network!

API description

API is described using OpenAPI specification: openapi-definition.yaml

Installation

Installation was tested with:

• Ubuntu 20.04 and Python 3.8
• Ubuntu 22.04 and Python 3.10

Program

Provided systemd and nginx configurations assume than program files are installed under /opt/csapi and service is running under csapi user.

Create csapi user:

sudo useradd -r -M -d /opt/csapi -s /usr/sbin/nologin csapi

Create /opt/csapi and /opt/csapi/socket directories:

sudo mkdir -p /opt/csapi
sudo mkdir -p /opt/csapi/socket
sudo chown csapi /opt/csapi/socket/

And copy files csapi.py and requirements.txt into /opt/csapi directory.

You will need to install support for python venv:

sudo apt-get install python3-venv

Then install required python modules into venv:

cd /opt/csapi
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Create configuration file /opt/csapi/config.yaml based on example configuration example-config.yaml. You need to either set parameter "allow_all" to "true" to disable client certificate check or specify list of trusted Client DN's. Disabled check means that all certificates trusted by Nginx would be allowed.

Configuration file contains Central Server management API token. Make sure configuration is readable only by csapi user:

chown csapi:csapi /opt/csapi/config.yaml
chmod 400 /opt/csapi/config.yaml

Create log directory:

mkdir -p /var/log/csapi
chmod 2750 /var/log/csapi
chown -R csapi:syslog /var/log/csapi

Systemd configuration

Add service description systemd/csapi.service to /lib/systemd/system/csapi.service. Then start and enable automatic startup:

sudo systemctl daemon-reload
sudo systemctl start csapi
sudo systemctl enable csapi

Nginx configuration

Add nginx configuration from this repository: nginx/csapi.conf to nginx server: /etc/nginx/sites-enabled/csapi.conf

Create a certificate for nginx (installed by default in X-Road Central Server):

sudo mkdir -p /etc/nginx/csapi
cd /etc/nginx/csapi
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout csapi.key -out csapi.crt

Cert info (NB! CN should be the domain name of your central server):

Country Name (2 letter code) [AU]:EE
State or Province Name (full name) [Some-State]:Harjumaa
Locality Name (eg, city) []:Tallinn
Organization Name (eg, company) [Internet Widgits Pty Ltd]:RIA
Organizational Unit Name (eg, section) []:CSAPI
Common Name (e.g. server FQDN or YOUR name) []:central-server.domain.local
Email Address []:

Make sure key is accessible to nginx:

sudo chmod 640 /etc/nginx/csapi/csapi.key
sudo chgrp www-data /etc/nginx/csapi/csapi.key

On client side (XTSS app):

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout client.key -out client.crt 

Cert info:

Country Name (2 letter code) [AU]:EE
State or Province Name (full name) [Some-State]:Harjumaa
Locality Name (eg, city) []:Tallinn
Organization Name (eg, company) [Internet Widgits Pty Ltd]:RIA
Organizational Unit Name (eg, section) []:APIClient
Common Name (e.g. server FQDN or YOUR name) []:
Email Address []:

Copy client.crt to Central Server machine: /etc/nginx/csapi/client.crt

For testing copy nginx csapi.crt to client and issue curl commands:

curl --cert client.crt --key client.key --cacert csapi.crt -i -d '{"member_class": "GOVXXX", "member_code": "XX000003", "member_name": "XX Test 3"}' -X POST https://central-server.domain.local:5443/member
curl --cert client.crt --key client.key --cacert csapi.crt -i -d '{"member_class": "GOVXXX", "member_code": "XX000003", "subsystem_code": "SystemXX"}' -X POST https://central-server.domain.local:5443/subsystem

Note that you can allow multiple clients (or nodes) by creating certificate bundle. That can be done by concatenating multiple client certificates into single client.crt file.

API Status

API Status is available on /status endpoint. You can test that with curl:

curl -k https://central-server.domain.local:5443/status

Testing

Install required python modules and dev tools into venv:

cd <project_directory>
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt -r requirements_dev_tools.txt

Running the tests:

cd <project_directory>
python -m unittest

Or alternatively run the test file directly:

python test_csapi.py

In order to measure code coverage run:

coverage run test_csapi.py
coverage report csapi.py

Alternatively you can generate html report with:

coverage run test_csapi.py
coverage html csapi.py

In order to lint the code run:

pylint csapi.py

Freezing requirements

In order to freeze python requirements so that production would have only module versions tested in dev/test environments you can create new venv and run pip freeze:

rm -rf venv
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip freeze -r requirements.txt -l > requirements_freeze.txt

Then you can install python requirements using requirements_freeze.txt file instead of requirements.txt