This repository contains information about the X-Road Catalog, its source code, development, installation and documentation.
X-Road Catalog is an X-Road extension that collects information on members, subsystems and services from an X-Road ecosystem and provides a REST and SOAP interfaces to access the data.
X-Road Catalog can be used together with an additional API Catalog component - a web portal that contains descriptions of all the services available in the ecosystem. The primary purpose of the API Catalog is to provide a user-friendly channel to search and discover available services. The API Catalog is targeted at both business and technical users.
When services are connected to X-Road, their service descriptions are published on the Security Server by the Security Server administrator. The service descriptions can then be accessed using a service discovery mechanism provided by X-Road. However, the mechanism is very technical and requires direct access to the Security Server's messaging interface. Also, getting a list of all services available in the ecosystem would require querying each Security Server separately. Therefore, a more user-friendly API Catalog is needed.
X-Road Catalog is used to automate the collection of the service metadata from the Security Servers. In that way, the descriptions need to be maintained in a single place only, and all the changes in the source are automatically updated to the API Catalog. Nevertheless, additional metadata must be manually added and maintained on the API Catalog by a service administrator representing the organisation owning the service. The metadata may include any information related to the service and its use, e.g., a more detailed description of the data set, terms and conditions, contact information, pricing information, SLAs, etc.
The X-Road Catalog software consists of three modules:
- X-Road Catalog Collector
- Collects information from the X-Road ecosystem (possibly also from external APIs) and stores it to the postgresql database.
- Implemented using concurrent Akka actors.
- X-Road Catalog Lister
- Provides REST and SOAP interfaces that offer information collected by the Collector.
- Can be used as an X-Road service (X-Road headers are in place).
- X-Road Catalog Persistence
- Library used to persist and read persisted data. Used by the X-Road Catalog Collector and X-Road Catalog Lister modules.
How to build X-Road Catalog?
See instructions in BUILD.md.
How to install and configure X-Road Catalog?
See the X-Road Catalog Installation Guide.
How to use X-Road Catalog?
See the X-Road Catalog User Guide.
Sign up for an account and get access to the X-Road Service Desk and X-Road Catalog Backlog.
Submit a pull request to X-Road Catalog source code Github repository or an enhancement request to the X-Road Service Desk.
When opening a pull request, please provide a signed Contributor Licence Agreement (CLA). More information can be found here.
The following activities, among others, are undertaken by the Nordic Institute for Interoperability Solutions (NIIS) with regard to X-Road Catalog:
- management, development, verification, and audit of the source code
- administration of documentation
- administration of business and technical requirements
- conducting development
- developing and implementing principles of licensing and distribution
- providing second-line support for the NIIS members
- international cooperation.
X-Road Technology Partners are enterprises providing X-Road consultation services, e.g. deploying independent X-Road instances, developing X-Road extensions and X-Road-compatible services, integrating informations systems with X-Road etc.
No support for X-Road Catalog deployment is provided here.
- X-Road Catalog was originally developed by the Finnish Digital Agency during 2016-2023.
- In 2023 it was agreed that Nordic Institute for Interoperability Solutions (NIIS) takes maintenance responsibility.