How to use IBM App Connect with shared APIs in IBM Cloud

You can use the API management capabilities of the IBM Cloud® platform to manage APIs natively, and can make your APIs available for discovery by sharing them with other developers who are in, or outside, your IBM Cloud organization. API management helps an organization control usage of its APIs, increase adoption, and track statistics. APIs that you share can include those that are created using integrated IBM Cloud services such as the App Connect service, APIs that are exposed by Cloud Foundry applications, and APIs that incorporate OpenWhisk® actions created using Cloud Functions.

If you are using an App Connect on IBM® Cloud service and have access to a set of APIs that are shared within your IBM Cloud organization, the shared APIs will be available in the App Connect catalog of applications and APIs. You must have Developer permissions in the organization. You can call a shared API from your App Connect flows and pass data between your shared API and other apps.

Availability:

Cloud-managed connector

The following information describes how to use IBM App Connect to connect shared APIs to your other applications.

A business scenario
What to consider first
Shared API guidelines and restrictions
Connecting App Connect to your shared API
Using a shared API in a flow
Responses and error case handling for flows
Updating a shared API in the App Connect catalog

A business scenario

The challenge

Your company is using IBM's open-standards cloud-based platform to help build key cloud solutions. Across the business, teams are provisioning infrastructure and platform services (or resources) in the IBM Cloud catalog to develop, run, and manage their applications. In your assigned IBM Cloud organization, developers use a single dashboard to manage the resources that are provisioned in your cloud environment. These resources include a set of APIs, which your team and others have created and shared using the native API management facilities. Your team would like to invoke some of these APIs from a set of automations that are currently being developed using App Connect flows, and would like a quick and easy way to do this.

How App Connect can help

From App Connect, you can directly browse through the set of shared APIs in your IBM Cloud organization. In the App Connect UI, a shared API's operations are exposed as actions, and its parameters are exposed as fields. So, when you use this API within your flows, you'll be able to easily specify query parameters for calls to the API and obtain responses you can act on.

What to consider first

For IBM Cloud access, you'll need:
1. An IBM Cloud account that you can log in to by using an IBMid:
  - Sign up for an IBMid and create your IBM Cloud account
  - Log in to an existing account
2. An App Connect service in IBM Cloud:
  - Provision a new App Connect service with a Lite plan
  - Access an existing App Connect service from your IBM Cloud Resources list
To use a shared API in App Connect:
1. You must have one or more shared APIs that meet the requirements for use in App Connect.
  More information:
  
  – Shared API guidelines and restrictions
  
  – Manage and share APIs in IBM Cloud
2. Then, connect App Connect to the shared API, so you can use it in your flows.
  More information: Connecting App Connect to your shared API

Shared API guidelines and restrictions

To successfully connect to and use a shared API in your App Connect flows, its API definition must meet a set of requirements which are identical to those for OpenAPI documents that are imported into App Connect. For more information, see:

Connecting App Connect to your shared API

To create an integration flow that passes data between a shared API, and other APIs, web services, or applications in the App Connect catalog, you must connect App Connect to each API, web service, and app in the flow. You can connect to a shared API only from the APIs tab on the App Connect Catalog page. You can connect to an imported API or web service from the APIs tab on the App Connect Catalog page, or when you add the API or web service to a flow. You can connect to an app either from the Applications tab on the App Connect Catalog page, or when you add the app to a flow.

To connect App Connect to your shared API, complete the following steps:

From the Catalog page, click the APIs tab. You'll see a list of:
- APIs that are shared in your IBM Cloud organization (if using an App Connect on IBM Cloud service).
- APIs that were imported by uploading OpenAPI documents. These APIs are tagged with an imported label . For more information, see How to use IBM App Connect with APIs imported from OpenAPI documents.
- Web services that were imported by uploading WSDL or ZIP files. These web services are tagged with an imported label also. For more information, see How to use IBM App Connect with SOAP web services.
Locate and click the shared API. The API is validated to see whether it can be used in App Connect.
- If any of these restrictions apply, the API is disabled with a message explaining why.
- If the API passes validation, you'll see the available actions (or operations) that you can use in flows.
Click Connect to display the connection fields.
Based on the security scheme that's configured for the API, perform one of the following actions:
- Specify a user name and password; for example, for basic authentication.
- Specify an API key; for example, to enable access and calculate usage of the API.
- Specify a user name and password, and an API key.
- Leave all the fields blank.
Click Connect again to add the account.

Tip: If you've configured more than one set of user credentials or generated more than one API key for the API (for example, to accommodate different rate limits or access levels), you can connect multiple accounts to the shared API application. For information about setting up multiple accounts, see Managing connection accounts in App Connect on IBM Cloud.

Using a shared API in a flow

A shared API can be used as a target application only and cannot be used as a source application that triggers a flow.

In the flow editor, only connected APIs are available for selection, so ensure you've connected the API on the Catalog > APIs tab if you want to use it in a flow.

Responses and error case handling for flows

The following details apply for flows that include a shared API:

The flow will continue on any 2xx (Success) or non-2xx HTTP status codes that are defined in the shared API definition.
The response status code returned for a shared API action is available for mapping within subsequent nodes in the flow if required.
If you want to change which status codes the flow can fail or continue on, you must update the shared API's definition in the originating system. Then, remove all existing accounts for the API in App Connect. The updated API will automatically be reloaded into the APIs tab on the Catalog page when you next try to connect.
The Available inputs list, which is accessible from the flow editor, will contain an entry for each of the defined responses for the operation. These will appear as an empty object if no schema was defined for that code in the shared API definition, but at run time will contain the response; so custom JSONata can be used to access these values.
Only one of the responses is populated at run time, but you can use an If node to check the status code to identify the response if required.

Updating a shared API in the App Connect catalog

If you want to replace a shared API with an updated version, you'll need to remove all existing accounts for the API in App Connect. The updated API will automatically be reloaded into the APIs tab on the Catalog page when you next try to connect.

For information about removing accounts, see Managing connection accounts in App Connect on IBM Cloud.