IBM API Connect Integration

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

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 SwaggerHub 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.

SwaggerHub needs an API key to connect to the IBM API Connect platform. To generate the API key:

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

SwaggerHub 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 SwaggerHub, 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.

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

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:

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

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:

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:

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 SwaggerHub. Select an operation on the left, specify parameters (if any) and click Call operation.

Click the image to enlarge it.

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: