Integration Namespaces

Integration Namespaces are used to consume other REST APIs (provided by other projects or external APIs). They support the Business Analyst and the Solution Developer to call operations of the referenced API and to map the response to the ubiquitous language of the project.

Each integration namespace supports modelling the following elements:

The first thing after having created a new integration namespace is to create an API Dependency and to provide the API specification of the REST API that you want to consume. This API specification can be either in OpenAPI 3.0 (.yaml) or Swagger 2.0 (.json) format. After providing the API specification, Solution Designer will create a type-safe interface for the operations defined in the API specification. This allows developers to program against the API as if it was a service locally defined in the project. In addition, Solution Designer abstracts common components such as API URL, path-, query- and *header-*parameters away, so that the developer only needs to provide the parameter values and (optionally) a request body in order to invoke the operation.

Note:

This step is not required but without providing an API specification the system cannot generate the methods to call the API operations. You can still make HTTP calls to any API, but you will have to implement each call on your own.

To use the operations, a REST Integration Service and its related Input- and Output- entities must be modelled in the integration namespace. When implementing the service, the developer can then call the operations and map from Input-entities to Parameters or Request Bodies as well as from Responses to Output -entities of services.

Tip:

The entities in Integration Namespaces can be used as 'known entities' of External Entities in the domain namespace.

Create Integration Namespaces

To create an integration namespace, use the Create capability in the Integration Namespaces section on the project's * Overview* page. Alternatively, you can use the Create capability in the left navigation bar after clicking on * Integrations*.

An integration namespace is defined by the following master data:

  • Prefix: This is the prefix of the namespace. It is unique within a solution. Please note, that only the characters A-z (without special characters), digits and the special character "_" are permitted for a prefix! Furthermore, prefixes may not begin with a digit and the first character must be lowercase. A prefix cannot consist more than 6 characters (required)
  • Label: This is used to give a short description of the integration namespace and its lifecycle (required)
  • Description: This is long the description of the integration namespace and its lifecycle (optional)

You can also use the Open after creation checkbox to open the integration namespace for further editing after saving.

Edit Integration Namespaces

You can edit the master data of a integration namespace by clicking the Edit namespace details button in the Namespace Details section on the integration namespace's instance page. The fields that can be edited are Label and Description.

Delete Integration Namespaces

You can delete an integration namespace by clicking the Delete namespace button in the upper right corner of the integration namespace instance page.

You cannot delete an integration namespace if:

  • a Property definition in a different namespace uses an Entity of the current namespace as a Range
  • a Property association in a different namespace uses an Entity of the current namespace as a Range Restriction
  • an Entity of the current namespace is used as a Parent in a different namespace
  • an Error of the current namespace is used in a Service or Command in a different namespace
  • a Service or a Command in a different namespace uses an Entity of the current namespace as Input/Output/Payload
  • an Entity from an integration namespace is used as a known entity in an External Entity in the domain layer
Warning:

You will be asked to confirm the action before the selected namespace is permanently deleted.

Migration of integration namespace with multiple API dependencies

It is suggested to have one API dependency for an integration namespace from IBM Industry Solutions Workbench 3.1 onwards. Hence, user's having Integration namespace with multiple API dependencies will be seeing the first API Dependency for the integration namespace in the General tab and a warning message on the right side of the page (above the Integration namespace details section).

The following steps are suggested to migrate the old API dependencies into individual Integration Namespaces:

  1. The user can click on the warning message which will open a sidebar card API Dependencies with the list of all existing API dependencies.

  2. A table listing all the API dependencies will be shown with three-dots-menu for each of the API dependencies.

  3. Use the three-dots-menu on the right side of a table row and click on Info. This will open a detailed View of the selected API dependency.

  4. In the Info view download the API specification file by clicking on the file name. Make sure to also copy the DEV binding if one exists in order to use it when recreating the namespace.

  5. Go ahead and create a new integration namespace.

  6. Create an API Dependency using the downloaded API specification file and if it exists the DEV binding.

  7. Repeat step 3 to 6 for all the API dependencies.

Warning:

The user will be able to use the older API dependencies without migrating but won't be able to add any new dependencies to an existing integration namespace (having more than one API dependency). Support for multiple API dependencies will be removed in a future release.