IBM API Connect Integration

IBM API Connect is an API operational platform that allows developers to create, run, manage and secure APIs in IBM Cloud. API Hub for Design integrates with IBM API Connect, so you can easily deploy and synchronize your API definitions on API Hub for Design with definitions in IBM Cloud.

Supported OpenAPI versions

The IBM API Connect integration supports only OpenAPI 2.0 definitions and has the following requirements for API definitions:

schemes must be set to use https only.
If an API uses an API key sent in: header, the key name must be either X-IBM-Client-Id or X-IBM-Client-Secret.

Considerations

Only the Cloud version of IBM API Connect is supported.
You need an IBM Cloud account. You can sign up for a trial here.
You must have an organization, space, and service instance configured in IBM Cloud.
IBM API Connect integration works only in one direction – from API Hub for Design to IBM API Connect. Any changes made to the API definition in IBM API Connect will not be reflected in API Hub for Design and will be overwritten.
IBM integration currently supports only the "us-south" region.

IBM extensions for OpenAPI specifications

IBM API Connect uses the x-ibm-configuration extension to store API configuration parameters specific to API Connect, such as the URL of the backend server to proxy the requests to. If you already have an API definition configured in IBM API Connect, simply import this definition to API Hub for Design to preserve the configuration.

You can also add these extensions yourself. For example, if you want to use IBM API Connect as a proxy for the existing API server, say, https://pokemons.mybluemix.net, you would use something like:

host: $(catalog.host)
x-ibm-configuration:
  phase: realized
  testable: true
  enforced: true
  cors:
    enabled: true
  assembly:
    execute:
      - invoke:
          title: invoke
          target-url: https://pokemons.mybluemix.net$(request.path)
          verb: keep
          description: Invoking the backend service

For a description of the x-ibm-configuration object properties, see IBM extensions to the OpenAPI specification.

Generate an IBM API key

API Hub for Design needs an API key to connect to the IBM API Connect platform. To generate the API key:

Log in to https://cloud.ibm.com/iam/apikeys.
Select IBM Cloud API keys on the left and click Create an IBM Cloud API key.
Click the image to enlarge it.
Enter the name and description for this API key and click Create.
Click the image to enlarge it.
Click Show, and then copy the generated API key, or download it to your computer. You will not see this key later on the IBM site.
Click the image to enlarge it.

Configure the IBM API Connect integration

To set up or change IBM API Connect integration, you must be the API owner or a collaborator with the Editor role.

Open the API page in API Hub for Design.
If the API has several versions, select the version you want to push to IBM API Connect.
If this version is published, unpublish it. Only unpublished APIs can be integrated with IBM API Connect.
Click the API name, switch to the Integrations tab, and click Add New Integrations.
Select IBM API Connect from the list of integrations.
Configure the integration (all the fields are required):
- Name – The display name of the integration.
- IBM Cloud API Key – The API key you generated earlier. Click Authenticate to display the rest of the options.
- Organization Name – The organization and space within your IBM Cloud account to which you want to deploy your API.
- API ID – Select the name of an existing API to publish to (it will be overwritten), or select <Create New API> to create a new API in API Connect.
- Enabled – Select this check box in order for the integration to work. Unselect it to disable the integration temporarily.
Click Create and Execute, then Done.

API Hub for Design will push your API definition to the specified API in API Connect, or create a new one. From now on, every time you save your API definition on API Hub for Design, the corresponding API definition in IBM API Connect will be updated. The name of the connected API is stored in the x-ibm-name key on the root level of your API definition.

View your API in IBM API Connect

You can view your API in the Drafts section of the IBM Cloud console:

Log in to https://cloud.ibm.com/apis/services.
Click your service instance.
On the left, click >> and select Drafts.
Switch to the APIs tab.
Click the image to enlarge it.
Click the API in the list to open it in IBM API Connect’s API designer.
Click the image to enlarge it.

Publish your API

A draft API is not yet available to anyone. To publish it, you need to add the API to a product (a group of APIs packaged together), then stage and publish this product to a catalog (a staging target). To do that:

In the API designer, click ··· in the top right corner and select Generate a default product.
Specify the product title, name and version. Select the check box to Publish this product to a catalog and select the catalog to publish to. You should have the default catalog named Sandbox.
Click the image to enlarge it.
Note
The option to publish the product to a catalog is not visible if you do not have any catalogs. To create a catalog, click >>, select Dashboard, then use the Add command.
Click Create product.
Tip
If you get the error “Product needs to provide both title and version.”, change the version format from 1.0 to another format such as 1.0.0, 1.0-beta, beta, or similar.
You should see a success message informing you that the product has been published to the catalog.
Click the image to enlarge it.

Your API is now available for external use. See Testing API Calls below for details.

Republish after changing the API

Once a product is published, every time you update the API definition, you must re-publish the product to reflect the changes in the catalog. To do that:

On the left, click >> and select Drafts.
Switch to the Products tab.
Click the product that contains your API.
In the top right corner, click the cloud icon and select the catalog. This will stage the product to this catalog.
Click >> again and select Dashboard to view your catalogs.
Click the catalog.
In the product list, click ··· next to your product and select Publish.
Click the image to enlarge it.

Test API calls

To test API calls, you need to know the base URL of the catalog to which the API is published. You can find it in the catalog settings:

On the left, click >> and select Dashboard.
Click your catalog in the list.
Switch to the Settings tab.
On the left, select Gateways.
Note down the base URL. It has the following format:
https://api.{region}.apiconnect.ibmcloud.com/{org}-{space}/{catalog-name}
Click the image to enlarge it.

You can test the GET methods directly in the browser by pasting this URL to the browser address bar and appending the basePath and resource path at the end:

https://api.{region}.apiconnect.ibmcloud.com/{org}-{space}/{catalog-name}/api/pokemons/1

Click the image to enlarge it.

You can also use the Explore tool in IBM API Connect to test all API operations in the catalog. To access this tool, click Explore and select the catalog name.

This opens interactive API documentation similar to the one you have in API Hub for Design. Select an operation on the left, specify parameters (if any) and click Call operation.

Click the image to enlarge it.

Troubleshooting

Error: "Unable to update API. If it was deleted, please remove the `x-ibm-name` extension and re-save your Swagger Definition."

This error can happen in the following cases:

The associated API was not found in IBM API Connect. For example, it could be deleted or its name (the Info.Name attribute in IBM API Designer) was changed. To resolve the issue:
1. Delete the integration.
2. Delete the x-ibm-name key from your API definition and save the changes.
3. Add the IBM API Connect integration again and specify whether to create a new API in IBM Cloud or to connect to an existing API.
The IBM API key used by the integration was revoked. To resolve the issue:
1. Generate a new IBM API key.
2. Open the integration settings in API Hub for Design.
3. Paste the new key and click Authenticate.
4. Click Save and Execute.