About REST APIs and System Interaction (Cloud Native Only)

Overview of REST API Support via System Interaction

JMS has long been the dominant mechanism for the exchange of messages between OSM and the external applications involved in order fulfillment. With REST APIs becoming increasingly common, OSM cloud native now provides capabilities for automation plugins to easily integrate with systems that use REST. In the TMForum ODA ecosystem for instance, there are TMF REST APIs describing all interactions traditionally involved in order fulfillment such as Partner Ordering, Shipping, Billing, Inventory, and Activation. A specific application instance may expose one of the TMF REST APIs or may offer a custom REST API - both are equally supported in OSM.

OSM cloud native offers a logical way to manage these interactions by modeling the API contract as an OpenAPI document, which is the System Interaction.

Terminology

The following table lists out common terminology that you need to be familiar with:

Table 7-1 Terminology

Name	Type	Description
Target System	Object	The logical name for an external system.
System Interaction	Object	This is an auxiliary resource in OSM that guides behaviour when processing an order fulfillment step that requires interaction with a Target System.
System Interaction API	API	This is the API presented by the external target system. The order fulfillment step for OSM needs to communicate with this API. The interaction might be as a client (to invoke operations) and as a server (to process asynchronous event responses). In UML, the client portion of this is termed a "Required Interface" and in TMForum Component, a "Dependent API".
System Interaction Specification	Specification	A System Interaction expressed as an OpenAPI, its API and its semantics.

System Interaction Specifications

When an OpenAPI document describing the REST APIs of an external system is imported into OSM, it is referred to as a System Interaction Specification. A System Interaction specification would generally be created for each functional interaction with an external system. The specifications are carried in multiple OSM cartridges - either TMF or Freeform. When the cartridges are deployed, the system interaction specification is persisted to the OSM database schema. From here, the System Interaction specification is accessed by the OSM Gateway microservice container. OSM Gateway uses this information for routing incoming and outgoing messages between OSM and the external system as well as handling JSON-XML payload transformation according to the schema.

Figure 7-1 System Interaction Specifications

Description of "Figure 7-1 System Interaction Specifications"

Expectations

This section highlights the expectations for the cartridge developer, administrator, and the OSM gateway.

External Application

You must provide an OpenAPI to OSM cartridge developers that captures the semantics of the REST APIs for the system, Operations, HTTP headers, path parameters, HTTP response codes, schema, server url and version and so on.
It ensures that only a single version is referenced inside the OpenAPI document. The info:version and version contained within the server:url must match.
A condition of any integration using System Interaction, is that external systems must honor the HTTP header used by OSM for correlation. External system async responses must echo back the HTTP header X-Correlation-ID that was sent on the request either as a HTTP header X-Correlation-ID or in event payload field correlationId.
Every operation in the OpenAPI document must contain an operationId field with a unique value to identifying the operation.
For an external system that emits events and notifications, the OpenAPI document that is provided to OSM cartridge developers must contain the path that OSM cloud native is expected to expose via its listener.

Cartridge Developer

Within each Order Component editor in Design Studio that needs to interact with a given Target System, import the OpenAPI specification for that Target System and provide a logical Target System name.
For each automation task in that Order Component, designates the task supports "System Interaction" (rather than the default "Direct JMS").
Writes sender automation plugin(s) to generate the payload (in XML) compliant with the API schema in the SI specification and identifies the REST operation to invoke for each.
Writes sender automation plugins(s) to set HTTP headers and path parameters if necessary.
Writes receiver automation plugin(s) to process the synchronous responses (HTTP codes and defined payloads) as XML.
Optionally, writes receiver automation plugin(s) to process event payloads as XML.
Provides a list of logical Target System names to the deployer or administrator.

Deployer (Administrator)

Ensures that all Target System names needed by a cartridge are listed in the project specification.
For each Target System logical name, identifies the actual target system for this particular instance.
For each Target System logical name, creates or updates the required configuration in the instance specification. At a minimum, this is the URL of the external system and will very often include some authentication details linked from a secret.
Ensures all required secrets are created as referenced in the target system configuration in the instance specification.
Creates or upgrades the OSM cloud native instance.
Ensures all external applications that act as a System Interaction Target System are properly configured with the OSM cloud native access URL and credentials.

OSM Gateway

Validates payload generated by sender automation plugin against SI schema, converts to JSON and uses this as payload to invoke the identified operation on the external system.
Handles transient communication errors with delays and retries.
Passes on hard failures and unresolvable transient failures back to the automation plugin.
Validates synchronous REST response against the SI spec, converts payload to XML and passes it on to the receiver automation plugin.
If automation plugins have registered for event notifications then OSM Gateway listens for incoming events, validates payloads against the SI specification, converts to XML and passes them on to the external receiver automation plugin.

Target System

The System Interaction Specification must define a Target System. This should be a logical name for the target system and should describe the function of the target system rather than its specific location. For example, a logical name of "Wireless-Activation" would be appropriate, as opposed to "Test-ASAP", as the latter pins it down to a specific system. This is important to allow flexibility between cartridge design and solution deployment design. The cartridge developer can freely reference a logical target system, leaving it up to the deployment scripts and configuration to allocate an actual target for that logical system in the form of a specific URL, authentication and so on. This target system is done via a two part configuration:

Design Configuration: In Design Studio, OSM Order Components have a System Interaction tab which provides for entry of the target system name.
Deployment Configuration: The logical target system name referenced in a cartridge must be defined in the actual CNTK deployment scripts. The CNTK holds the logical target system name in the project specification while the connection details like URL and authentication are defined in the instance specification. At runtime, OSM Gateway will resolve the logical target system name for a given System Interaction Specification by reading deployment artifacts created by the CNTK during instance creation.

Figure 7-2 Deployment Configuration

Description of "Figure 7-2 Deployment Configuration"

About Modeling Fulfilment Using System Interaction Specifications

The System Interaction feature is available for both Freeform and TMF cartridges. Refer to the "Modeling External REST Interactions using System Interaction" in the OSM Modeling Guide for further details.