Interacting via REST between Platform registries and with external systems

1. General description

The Platform supports integrative interaction of registries using REST API interfaces. This interaction is made 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.

Main functions of the inter 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. Inter registry REST interaction schemes

There are two schemes of integration of 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 needs to initially obtain an access password from the registry administrator. With this password, it can obtain an access token in the Keycloak service. This token can then be used for authorization in services and accessing resources.

    • The external-system-api-kong-proxy service is automatically deployed along with the register and has a REST interface that allows initiating business processes in registers 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 accessing 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:
The registry client needs to obtain an access token from the Keycloak service for another registry. This token can be used for authentication in the services.

  1. Through the bp-webservice-gateway service, which is automatically deployed with the registry and has a REST interface allowing the initiation of business processes in the registries on the Platform 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 special 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 special 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.

  • For external systems, it is important to obtain an access token to the registry from Keycloak to use it for further authorization in registry services. An example of implementing token retrieval logic through Postman can be found here: Obtaining authorization token from external systems.

  • A separate scenario is configuring outbound interaction with external systems, where the registry on the Platform needs to call other systems. This can be done using a REST connector (see Outbound integration with 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 for 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.

    Example .bpmn process model, as well as custom .json forms for it, can be found in the consent-data demo registry regulatory document at the following link: https://admin-tools-consent-data.apps.envone.dev.registry.eua.gov.ua/gerrit.

    The process will be available under the name BPMN-create-school-auto.bpmn. You can find the form names inside the respective 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:

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

    • Retrieve data from the operational database of another registry on the Platform - use the standard integration extension-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 that are expected by it.

      For example, 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 condition. This 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 to the database of another registry based on the search condition from the UI form.

3.3. Obtaining authorization token from external systems

To access registry resources, an external system needs to obtain a special access token --a JWT token. 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

The functionality description includes related pages from the documentation. They are listed in this section for convenience.