App Connect

Invoking IBM App Connect Enterprise REST APIs from IBM App Connect Designer flows on Cloud Pak for Integration

By Jonathan Roberts posted Mon November 02, 2020 11:21 AM

  
This blog will show the steps to take a REST API that is running in an IBM App Connect Enterprise (ACE) Integration server and expose it and invoke it in an App Connect Designer flow. One of the ways that this can be achieved is by using the OpenAPI connector. This allows App Connect Designer to model the request and the response parameters based on the contents of the OpenAPI (previously known as Swagger) document representing the REST API.

Scenario
A city administration has an API (which is running as an App Connect Enterprise REST API) to provide live status for different categories of bed that are available for COVID-19 positive patients across all hospitals in the city.
‘AH Health Provider’ plan to consume this API in their health app and provides the relevant hospital suggestion to patients based on patient location, bed availability and patient health needs. They are planning on using App Connect Designer to consume this API in order to integrate it with other SaaS systems that they use.
App Connect Designer provides a way of importing an OpenAPI (v2) document which represents a REST API. Accounts can be created to connect to this API using one of several supported authentication mechanisms. The input and output properties will be modeled and are represented graphically in the App Connect Designer mapping tools when creating a flow.

Export the REST API from ACE
The team providing the REST API which is running on ACE can export an OpenAPI v2 document which describes the API. They can make this available to consumers who wish to invoke their API. 
To do this find the integration server in ACE and navigate to the REST API in question in the App Connect Dashboard
REST API on an integration server

Selecting this HealthProviderBeds REST API will display details of the API as well as offering the chance to try it out by using a test client. Clicking on the "Download Open API Document" icon will download the OpenAPI document
.
Download REST API


Consuming the API in App Connect Designer
The team wishing to consume this API have decided to use App Connect Designer to create a flow linking several of their existing SaaS applications to the new API. They are using App Connect running on Cloud Pak for Integration, although all of the features are also available on the managed cloud.

Create an instance of Designer in IBM Cloud Pak for Integration
For full details of installing App Connect designer in IBM Cloud Pak for Integration see https://www.ibm.com/support/knowledgecenter/SSTTDS_11.0.0/com.ibm.ace.icp.doc/certc_install_designeroperandreference.html.
If an instance of App Connect Designer isn't already available, one can be created on IBM Cloud Pak for Integration. When creating a new capability, select "App Connect Designer", then follow the steps in the UI to create a new instance of App Connect Designer.
Designer on CP4i


Import the OpenAPI document into Designer
In order to have the API represented as a first class connector, it needs to be imported into Designer. This allows the API to be called from multiple flows and once set up, the users creating the flows don't need to be concerned about the connection details backing the API. This example is using an OpenAPI document downloaded from an ACE integration server, but the OpenAPI document could represent an API running anywhere. For more details about the OpenAPI connector see https://developer.ibm.com/integration/docs/app-connect/how-to-guides-for-apps/use-ibm-app-connect-openapi/.

Import the API from the APIs tab on the Catalog page and using the "Add your API now" option.
Add API


Select the OpenAPI document and give it an appropriate name, then upload it. 
Upload API


The API will now appear in the list of APIs and can be treated in the same way as any other connector.

Create an account for this API by clicking "Connect". This gives the chance to enter any authentication details needed for connection (for example basic auth details or an API key).
Tip: when using a non-production environment specifying that self-signed certificates should be permitted might be required. 
Connect to API

Using the API in a flow
Now that an account has been created, the API can be used in a flow like any other connector. Select the operation that should be called, in this case that is the action GET /getBedStatus. The mapper will show the request and response parameters that are available to be used.
API input props

The properties of the response are modeled and can be used in a node further on in the flow.
Response properties

When invoking the API (shown here using the "Try this action" button to test during development) parameter validation is performed against the specification defined in the OpenAPI document. In this example a required parameter is missing so an error returns.
Response error


When successful, the fields of the response can be mapped into nodes further in the flow.
Successful flow


Summary
This blog has stepped through exporting a REST API from an ACE integration server as an Open API document. This OpenAPI document was then used to connect to that API in App Connect Designer running on IBM Cloud Pak for Integration and the input and output properties were modeled so they could be integrated into a flow.

The examples given are all running in IBM Cloud Pak for Integration containers running on an OpenShift environment, but are all applicable for App Connect running on IBM Cloud too.

#Featured-area-1
#Featured-area-1-home

Permalink