Interacting via REST between Platform registries and with external systems

🌐 This document is available in both English and Ukrainian. Use the language toggle in the top right corner to switch between versions.

1. General description

The Platform supports integrative interaction of registries using REST API interfaces. This interaction is possible due to the Inter registry integration subsystem.

The functionality ensures interoperability of the Platform, providing access to business processes and data reading APIs, as well as allowing reading data and invoking business processes in other registers.

By default, the Platform utilizes cross-registry interaction between registers through the Ukrainian Secure exchange gateway (SEG) Trembita (for details, see trembita.gov.ua). This interaction is carried out using the SOAP protocol. It requires resolving preparatory matters in the legal domain.

Cross-registry interaction via REST reduces excessive utilization of computational resources, external traffic, and response time in register integration without employing SOAP interfaces of the Trembita SEG and moving away from complex bureaucratic mechanisms.

Main functions of the cross-registry integration subsystem:

  • Providing an API for invoking registry business processes by external systems.

  • Providing access for other registries or systems to individual data read requests of the registry data management subsystem.

  • Routing requests to external registries with granted access.

2. Cross-registry interaction: REST schemes

There are two integration schemes for the registries deployed on the Platform:

2.1. REST interaction of registries on the Platform with an external information system

Integration interaction of registers with external systems can be divided into outbound and inbound, depending on the direction of traffic.

int reg ext system
Figure 1. Interaction of registries on the Platform with a third-party information system

  1. Outbound interaction is possible through the integration REST connector — Connect to external system. The connector has a REST interface for calling external endpoints. It can be used when modeling business processes in the regulations of a specific register. OpenShift (Kubernetes) secrets should be used for authentication.

  2. Inbound interaction is possible through the implemented registry services: external-system-api-kong-proxy and registry-rest-api-ext.

    The external system must initially obtain an access password from the registry administrator. With this password, it can get an access token in the Keycloak service. This token can then be used to authorize in services and access the resources.

    • The external-system-api-kong-proxy service is automatically deployed along with the register. It has a REST interface allows initiating business processes in registries on the Platform and retrieving data from them. The service uses the entry point (endpoint) /startBp to start a business process.

    • The registry-rest-api-ext service is automatically deployed after creating the data model in the registry regulations. It allows access to API representations of the registry operational database.

2.2. REST interaction of registries within a single Platform

During the integration interaction of registries within the Platform, there is always a registry client (data consumer/requester) and a target registry (data owner).

internal registries platform
Figure 2. REST Interaction of registries within a single Platform
The registry client can request data from the target registry in two ways through:
The registry client needs to obtain another registry’s access token from the Keycloak service. This token can be used for authentication in the services.

  1. The bp-webservice-gateway service, which is automatically deployed with the registry and has a REST interface, allows business process initiation in the Platform’s registries and retrieving data from them. The service utilizes the entry point (endpoint) /startBp to start a business process.

    • Initiating business processes in another (target) registry is possible using a delegate extension called Start business process in another registry. It is designed solely for registry integration within the Platform.

    • To retrieve data from the operational database of another (target) registry within the execution of business processes, a delegate extension called Search for entities from another registry data factory can be used. It is intended only for registry integration within the Platform.

  2. Through the registry-rest-api-ext service, which is automatically deployed after creating a data model in the registry regulations, it is possible to access the API representations of the registry’s operational database from the User interface (based on search condition) in the User portal.

3. Setting up interaction between registries

Configure REST interaction with other registries within a single Platform instance or external systems.

3.1. Configuring target registry (data owner)

If your registry is the data owner, and you want to expose integration API endpoints, receive requests, and provide data to other registries or systems, perform the following regulations settings:

  1. Configure authorization settings—provide access to invoking the business process.

  2. Model the business process to be invoked by another registry.

  3. Create a data model (grant read access to the registry data through the API representation).

For more details on setting regulatory requirements for steps 1-3, refer to Configuring the regulations to provide access to data via SOAP and REST APIs.

  1. Also, for REST interaction, grant access to the registry for another registry on the Platform or external system in the Control Plane administrative panel. Administrators can add, delete, or suspend access to the registry for other registries on the Platform and external systems.

    For more details, see Configuring registry access.

3.2. Configuring the client registry (data consumer)

Configure interaction with other registries for the data-consuming registry. To do this:

  1. Model the business process with the ability to call an external registry.

    Where can I find an example of a reference business process?

    The Platform administrator can deploy for you a demo-registry  — a reference registry containing reference and other example files for creating a digital registry regulations. It includes various elements for developing data models, business processes, UI forms, analytical reporting, extracts, notifications, external integrations, and more.

    Detailed instructions on deploying the demo-registry and obtaining reference modeling examples can be found on page Deploying demo registry with reference examples.

    An example of a BPMN process diagram will be available in the demo-registry’s regulations by searching for the keywords — create-school-auto. The names of the forms can be found inside the corresponding User Tasks of the business process in the Form key field.

  2. Within the business process, use standard integration extensions to interact with other registries on the Platform:

    • Launch business processes in another registry on the Platform—use the standard integration connector—Start business process in another registry.

    • Retrieve data from the operational database of another registry on the Platform—use the standard integration connector—Search for entities from another registry data factory.

      For descriptions and configurations of delegates, see Integrating extensions.

      To start a business process in the target registry, you need to pass the initial variables expected by it.

      You can pass the initial variables as a Map of input parameters (Input Parameters), for example, as key-value pairs when configuring the delegate for starting the business process.

      pass map params bp
      Figure 3. Formation of initial variables of the process in the client registry for transfer to the target registry

  3. Model a UI form to read data from the operational database of the registry based on search conditions. This scenario allows accessing the database of another registry from a user form. To do this:

    • Go to the Regulations administrator portal> Open the UI Forms section > Create a data input form > Open the Form builder.

    • In the Select component, switch to the Data tab > In the Data Source URL field, enter the path to the resource in the data factory of another registry.

      Example 1. Data Source URL field on the UI form
      /api/integration/data-factory/test-registry/resource-name

      Parameter/Path

      Description

      /api/integration/data-factory

      Root path (unchanged).

      test-registry

      Service name of the target registry specified in the Control Plane.

      resource-name

      Name of the resource/endpoint to be accessed for data retrieval. For example, /edu-type.
      create sc data source url
      Figure 4. Request the database of another registry based on the search condition from the UI form

3.3. Obtaining authorization tokens from external systems

An external system must obtain a unique access token, the JWT, to access registry resources. It is intended for further authorization of external systems when interacting with registries deployed within the Platform.

For more details, see Calling the registry from an external system: getting a JWT token from Keycloak.

3.4. Outbound integration with external systems

If there is a need to integrate with an external service or a system outside the Platform cluster, use a special REST connector — Connect to external system.

For more details, see Integration with external services using the REST connector.

3.5. Related pages