How to use IBM App Connect to discover and import APIs from IBM API Connect

IBM API Connect is an integrated API management offering that you can use to create, manage, secure, and socialize APIs across your business and ecosystem. API Connect includes capabilities and tools for all phases of the API lifecycle. In an IBM Cloud Pak for Integration deployment on Red Hat® OpenShift®, you can discover and import APIs from an API Connect instance into App Connect. You can then connect to the API endpoints and use the imported APIs to invoke the API operations from your flows.

Availability:

App Connect Enterprise as a Service connector
Local connector in containers (Long Term Support Cycle-3 release) 13.0.7.0-r1 or later
Local connector in containers (Continuous Delivery release) 12.0.10.0-r2 or later
Local connector in containers (Long Term Support Cycle-2 release)

What to consider first

In API Connect, members of a provider organization create, publish, and maintain APIs, which application developers in a consumer organization can subscribe to and use. Each provider organization publishes its APIs to a Developer Portal to make the APIs available to consumer organizations.

API providers package their APIs into Products for distribution to API consumers, and define Plans (with monetization schemes) within those Products to control access to the APIs and to manage API usage. In a typical workflow, an API provider develops APIs, adds them to draft Products with defined Plans, and then stages the Products to a development Catalog. When development and testing are complete, and the APIs are ready for external use, the Products are then published to a production Catalog on a Developer Portal. A Catalog uses an associated gateway service with defined gateway policies to handle any API requests for the APIs in that Catalog. For more information about API Connect concepts, see API Connect overview in the API Connect documentation.

You can discover APIs in Products that are staged or published to Catalogs in an API Connect instance and then import these APIs into the App Connect Designer catalog.

Prerequisites for discovering APIs from API Connect

To enable App Connect to discover APIs from API Connect, the following prerequisites, which also mostly apply for unified authoring, must be met:

Cloud Pak for Integration 2023.4.1 or later must be installed in your cluster and an IBM Cloud Pak Platform UI instance, which enables you to create and manage instances of capabilities from a central location, must be deployed in all namespaces (cluster-wide), or in a single namespace in your cluster.
You must have access to an App Connect Designer instance (of type Integration design) at version 12.0.10.0-r2 or later, and an API Connect instance (of type API management) at version 10.0.7.0 or later, which are deployed to the Platform UI in your cluster. The App Connect Designer and API Connect instances can be in the same or different namespaces if Cloud Pak for Integration and the Platform UI are deployed cluster-wide. For more information, see Installing the Operators and API Management deployment in the Cloud Pak for Integration documentation.

In this environment, identity and access management (IAM) is enabled by using Keycloak, which is used to validate user identities and assign roles to grant access permissions. The App Connect Designer instance must also be created with a CloudPakForIntegration* style license. This value is set by the spec.license.use parameter in the Designer custom resource. For more information, see Identity and access management in the Cloud Pak for Integration documentation and Identity and access management for App Connect Designer and App Connect Dashboard instances on Red Hat OpenShift.
The API Connect instance (of type API management) must be configured by using the Cloud Manager user interface (of type API management administration) to register the relevant servers to provide gateway, analytics, and portal services. For more information, see API Connect admin: manage the API Connect environment and users. Work with your administrator if necessary to ensure that these specific requirements are met:
- A DataPower API Connect Gateway Service must be installed as a subsystem in your cluster and a DataPower API Gateway service must be registered to handle incoming traffic for APIs. A DataPower API Gateway service, rather than a DataPower Gateway (v5 compatible) service, is required to support the discovery of APIs that conform to the OpenAPI Specification Version 2.0 or 3.0.x, which is supported only with DataPower API Gateway. For more information, see Registering a gateway service.
  
  (A Gateway service represents a cluster of gateway servers that host published APIs and provide the API endpoints that are used by client applications. Gateways run API proxy invocations to backend systems and enforce API policies including client identification, security, and rate limiting.)
- You must be logged in to App Connect Designer (through the Platform UI) by using a user account that is set up in the API Connect Cloud Pak User Registry. This user account must be assigned the designerauthoring-admin role, which assigns full access and is required for any action in Designer. For more information, see Roles and permissions for App Connect Designer.
  
  Tip: API Connect configures Cloud Pak for Integration IAM as the API Connect user registry called Cloud Pak User Registry. API Connect's single sign-on with Cloud Pak for Integration applications works only if you choose Cloud Pak User Registry when logging in to API Connect.
- The API Connect environment that you are logged in to (under your Cloud Pak User Registry account) must contain at least one provider organization, which is set up to manage teams that develop and manage APIs and related assets. You must either be registered as the owner of a provider organization, or registered as a member of a provider organization with a Developer role that is assigned at the provider organization level. For more information, see Creating a provider organization and API Connect user roles.
A Sandbox Catalog, which is available by default, or a user-defined Catalog must exist in the provider organization. The Catalog to which you stage and publish Products (and APIs) must contain an application that has an owning consumer organization and is secured with a client ID and client secret.
One or more Products must be staged or published to at least one Catalog in API Connect to enable discovery of the APIs in App Connect Designer. For information about creating and managing Catalogs, Products, and APIs, see Working with Catalogs, Working with Products, and Working with API definitions.

Restrictions for APIs that can be imported into App Connect Designer

You can import APIs that conform to either the OpenAPI Specification Version 2.0 or 3.0.x into App Connect Designer. However, a set of restrictions apply for API definitions that can be imported into App Connect Designer.

Only APIs with an apiKey security scheme are supported. In API Connect, configure this scheme by adding a client_id key type with a variable value of X-IBM-Client-Id, and a client_secret key type with a variable value of X-IBM-Client-Secret. For more information, see Defining API key security schemes (OpenAPI 2.0) and Defining API key security scheme components (OpenAPI 3.0). The following example shows the Design tab for an OpenAPI 3.0 API definition with configured apiKey security scheme settings for a client ID and client secret.
Some other elements of an API definition in API Connect might not be supported in App Connect Designer. If you try to import such APIs, the import fails and an error message is displayed. For information about OpenAPI restrictions for importing APIs into App Connect Designer, see Restrictions.

For limitations to the OpenAPI 3.0 support in API Connect, see OpenAPI 3.0 support in IBM API Connect.

Discovering and importing an API into App Connect

Complete these steps to discover and import an API from a staged or published API Connect Product into App Connect:

From the App Connect Designer Connect > Applications and APIs page in App Connect Designer, click the Add connector or API icon (+).
Complete the Add a connector or API panel as follows:
1. From the Import or discover view, select Discover an API from IBM API Connect, and then click Next.
  
  The Select an API catalog view opens with individual tiles that represent each Catalog that you can access in your API Connect instance. Each tile displays the Catalog name and the provider organization where the API is staged or published. If you have access to an API Connect instance, you should at least see the Sandbox Catalog that is allocated to each instance by default, and which cannot be deleted.
  
  Tip:
  If no Catalogs are displayed, verify that an API Connect instance exists in your Cloud Pak for Integration deployment, and that you are authorized to access the instance to work with APIs.
  
  Also verify that your App Connect Designer instance is created with a CloudPakForIntegration* style license. App Connect Designer instances with an AppConnectEnterprise* style license do not support API discovery.
2. From the Select an API catalog view, click the API Connect Catalog that contains the Product and API that you want to discover and import. Then, click Next.
  The Select an API from the catalog catalogName view opens with a collection of Products that are staged or published to the selected Catalog.
  
  If the Catalog is partitioned into Spaces, to enable multiple teams to manage Products and APIs independently in a single Catalog, the Products that are staged or published to each Space are listed in a consolidated view. For more information about Spaces, see Using syndication in API Connect.
  
  If no Products are displayed, verify whether the selected Catalog contains any staged or published Products in your API Connect instance.
3. Click to expand the appropriate Product, select the API that you want, and then click Next.
4. From the "Review properties" view, update the fields if necessary:
  - Name: The name is inherited from the title of the API in API Connect, but you can update it if preferred. Specify a unique name of up to 30 characters by which the API can be identified on the App Connect Designer Applications and APIs page or within the flow editor.
  - Description: The description is inherited from the API description if specified in API Connect, but you can add a new description to summarize the functions of the API if preferred. Up to 250 characters are allowed.
  The defined operations in the imported API are displayed as actions.
5. Click Import API.
  The imported API is shown in the Not connected list of connectors in the App Connect Designer Applications and APIs page. Expand the API to view the available actions that you can use in your flows, and to connect to the API.

Connecting App Connect to the imported API

To connect to the imported API from App Connect Designer for the first time, complete the following steps.

From the App Connect Designer Applications and APIs page, find the imported API, and click to expand it.
Click Connect to display the connection fields.

Applicable for an API that conforms to the OpenAPI 3.0.x Specification: The Server URL field, which is shown as the first field, displays the full URL endpoint for invoking the API, taking into account any vanity endpoint configuration in the Catalog to which the API is published. The typical formats for this URL, which is derived from API Connect, are as follows:
```
https://gateway_service_host/provider_organization/catalog/basepath

https://gateway_service_host/provider_organization/catalog/hostName/basepath
```
If more than one basepath value is specified as the server URL in the API definition in API Connect, the first one is used.

An example of the full Server URL value is:
```
https://small-gw-gateway-apic.apps.acecc-cd-apic.abc.com/mattporg/feedee-catalog/api.holded/api
```
Complete the fields that are specific to the API key security scheme, which is the only supported scheme. The field names that you see are inherited from the API definition in API Connect. For more information, see Defining security schemes (OpenAPI 2.0 API definition) and Defining security scheme components (OpenAPI 3.0 API definition).
To complete the X-IBM-Client-Id and X-IBM-Client-Secret fields, click Generate credentials to populate the fields with an auto-generated client ID and client secret. If credentials cannot be generated, you can manually specify valid values that you added for an application in the API Connect Catalog.

Tip: Reveal the generated client ID and client secret in the X-IBM-Client-Id and X-IBM-Client-Secret fields, and copy the values to a safe location. If you later use this imported API and account in a flow and then export the flow to a BAR file for deployment to an integration server or integration runtime, you will need to specify this client ID and client secret when you create a configuration object of type Accounts. For more information, see Connecting to APIs that are discovered and imported from API Connect.
When you click Generate credentials, App Connect creates the following artifacts in the Catalog where the API is published:
- A consumer organization that is named in the format UDA.default.openapi.APIname-appconnect; for example, UDA.default.openapi.Holded-appconnect. Only one consumer organization is created per API.
- An application that is named in the format UDA.default.openapi.APIname-appconnect, and client credentials. Only one application is created per API, but multiple client credentials can be generated.
- A subscription. Only one subscription is created per application.
- This image shows an example of a consumer organization, an application with credentials, and a subscription that are generated for a Catalog in the API Manager UI when you click Generate credentials in Designer.
If appropriate, complete one or more of the standard fields that are displayed for all imported APIs.
- To be able to accept self-signed certificates that are trusted and used only in a nonproduction environment, set Allow self-signed certificates to true.
- Applicable for an API that conforms to the OpenAPI 2.0 Specification: If you want to override the base path in the API definition, specify an override value in the Override the base path for the API field. The base path is the initial URL segment of the API (excluding the host name or any additional segments for paths or operations) and is shared by all operations in the API.
- Applicable for an API that conforms to the OpenAPI 2.0 Specification: If you want to access the API by using a host address that is different from the API endpoints that are defined for the gateway services where your API runs, specify an override in the Override the host name and port of the API server field. Specify the protocol, host name or IP address, and the port number of your preferred location in the format http://host:port or https://host:port. (Leave the Private network connection field blank). When you create and run a flow, the https://gateway_service_host segment of the API endpoint is overwritten with the specified protocol, host, and port. This setting enables you (or multiple users of the Designer instance) to use the same flow to call different or custom endpoints for the API by setting up multiple accounts with different override URLs.
- Applicable for an API that conforms to the OpenAPI 3.0.x Specification: If you want to override the https://gateway_service_host segment of the server URL (for example, https://small-gw-gateway-apic.apps.acecc-cd-apic.abc.com), complete the Override server URL field. Specify the protocol, host name or IP address, and the port number of your preferred location in the format http://host:port or https://host:port. (Leave the Private network connection field blank). This setting enables you (or multiple users of the Designer instance) to use the same flow to call different or custom endpoints for the API by setting up multiple accounts with different override URLs. When you create and run a flow, the server URL is overwritten as shown in the following example.
  Original server URL:
```
https://gateway_service_host/provider_organization/catalog/basepath
```
  Overwritten server URL:
```
https://host:port/provider_organization/catalog/basepath
```
- If the API endpoint is on a private network (for example, behind a firewall in an on-premises location), complete both of these fields:
  - Override server URL or Override the host name and port of the API server: Replace the https://gateway_service_host segment of the server URL or API server with the protocol, host name or IP address, and port number of an endpoint in a private network. Use the format http://host:port or https://host:port.
  - Private network connection: Select the name of a private network connection that App Connect uses to connect to your private network. This list is populated with the names of private network connections that are created from the Private network connections page in the Designer instance. You see this field only if a switch server is configured for this Designer instance. For more information, see Connecting to a private network from App Connect Designer. (In App Connect Designer 12.0.10.0-r1 or earlier instances that include this field, the display name is shown as Agent name.)
  When you create and run a flow, the URL is overwritten and the API request is routed through the private network connection to the protected endpoint.
Click Connect.
An account is created in App Connect, and the API is transferred to the Connected list of connectors on the Applications and APIs page. By default, the account is named Account 1, but you can use the Account menu to rename it so that it's easily identified when you add it to a flow. You can now use the imported API in your flows.

Using an imported API in a flow

When you create a flow in App Connect Designer, you can use an imported API as a target application by adding actions to invoke the API's operations. You cannot use an imported API as the source application that triggers a flow.

For more information about using an imported API in a flow, see Creating flows from scratch in App Connect Designer.

Removing an imported API from the App Connect Designer Applications and APIs page

If no longer needed, you can delete an imported API from the Applications and APIs page by clicking the Remove this API (or Remove this connector) link for the API. This link is visible only if the API is not being used in any flows and if all accounts for the API have been removed.

"Remove this API" link for removing an imported API from the Catalog page