Importing an OpenAPI document into App Connect as an API (App Connect Designer instance in a containerized environment)

Importing an OpenAPI document into App Connect Designer 12.0.10.0-r2 or later

Complete these steps to add an imported API to App Connect:

1. From the App Connect Connect > Applications and APIs page, click the Add connector or API icon [+].
   
2. Complete the Add a connector or API panel as follows:
   1. From the Import or discover view, select Import a connector file or API document, and click Next.
      
   2. From the Import document view, select OpenAPI from the Document type list.
   3. Specify the file that you want to import. The file can be in a local or network drive, and can have any of these file extensions: .json, .yaml, or .yml. You can either drag the file from its location in an open file browser into the Import box, or click within the box to open a file browser and locate the file. The file name is displayed in the Import field, as shown in the following example.
      
   4. Click Next.
   5. From the Review properties view, complete the fields as follows:
      • Name: Specify a unique name of up to 30 characters by which your API can be identified on the Applications and APIs page or within the flow editor.
      • Description: Summarize the function of the API. The description is taken from the description property in the imported file if one exists, but you can update this field as required. Up to 250 characters are allowed.

      The defined operations in the imported file are displayed as actions. For information about how these actions are grouped, see OpenAPI document guidelines.

      
3. Click Import API. Your API is displayed on the Applications and APIs page with a Not connected status.

   You can expand the API to view the available actions. To use these actions in your flows, you'll need to specify account credentials as described in Connecting App Connect to your imported API (App Connect Designer instance in a containerized environment).

   

Updating an imported API in App Connect Designer 12.0.12.3-r1 or later

If you need to update the OpenAPI definition of your API, you can make the update in a tool of your choice by either overwriting the existing definition or by creating a new version of the API. You can then choose to apply this update to a previously imported version of the API in App Connect Designer.

• You can replace the existing imported API in the App Connect Designer Applications and APIs page by importing the updated OpenAPI document.
• You can add another version of the imported API to the Applications and APIs page to co-exist with the existing imported API by importing the updated OpenAPI document. Both imported APIs are shown with the same name, but with different versions.

When you update the OpenAPI definition of your API, update the version by adopting the semantic versioning standard that the Connector Development Kit uses for connector version control. The Connector Development Kit enables you to create community connectors that can be shared with other users and is a component of IBM Automation Explorer. The Connector Development Kit uses a three-part version format of Major.Minor.Patch to define the magnitude of the change between versions. For example, the first version of a community connector is 1.0.0 by default, and you could subsequently assign versions such as 1.0.2, 1.1.0, or 2.0.0 if you decide to create new versions of the connector with patch, minor, or major updates. For more information, see Defining a connector version and Managing connector version in Connector Development Kit in the Connector Development Kit documentation.

Typical scenarios for an update are as follows:

• If you have breaking changes in an API, you can choose to upgrade or downgrade the major version of the imported API in App Connect.
• When you make additive or non-breaking changes to an API, you can upgrade the minor version of the imported API in App Connect.
• When you make changes that are compatible with an earlier version of an API or fix bugs in the API, you can upgrade the patch version of the imported API in App Connect.

Before you update an imported API in App Connect Designer, ensure that the following prerequisites are met:

1. Ensure that the Major.Minor.Patch version for your updated OpenAPI definition is in accordance with the criteria for version updates.
2. Save the OpenAPI document for the updated version of your API to a location of your choice.
3. From App Connect Designer, complete the relevant action:
   • If you intend to import an OpenAPI document that contains a major version update and use it to replace an imported API of the same name that exists in the Applications and APIs page, delete any flows that reference your existing imported API, and delete any accounts that are created for the imported API. Before you delete the flows, consider whether you want to export them so that you can import them after you replace the imported API. (You do not need to delete any flows or accounts if you intend to import the OpenAPI document as a different version that co-exists with the existing version of the imported API in the Applications and APIs page.)
   • If you intend to import an OpenAPI document that contains a minor or patch version update and use it to replace an imported API of the same name that exists in the Applications and APIs page, stop any running flows that reference the existing version of the imported API.

The following image shows an example of an API that was imported into the Applications and APIs page with an initial version of 1.0.0.

Complete these steps to add an updated version of an imported API from the Applications and APIs page:

• For a major version update, complete the following steps:
  1. Follow the steps to import the updated OpenAPI document for an imported API into the App Connect Designer Applications and APIs page. The following example shows the OpenAPI file for a major version of an API that you want to import.
     
  2. When you get to the Review properties view, choose either of these options:
     • Click Create a new connector to create a different major version of the API in the Applications and APIs page without replacing the existing API.
     • Click Replace existing connector to replace the existing version of the API with the new version.
     
  3. Click Import API.

     If you chose to create a new version, the existing API and newly imported API are both displayed on the Applications and APIs page.

     

     If you chose to replace the existing API, the existing API is overwritten with the newly imported API on the Applications and APIs page.

     
  Tip: The version of an imported API is displayed on the Applications and APIs page only if the version is 2.0.0 or later. When you add an action for an imported API to a flow, the version is always displayed in the flow editor regardless of the number.
• For a minor or patch version update, complete the following steps:
  1. Follow the steps to import the updated OpenAPI document for an imported API into the App Connect Designer Applications and APIs page. The following example shows the OpenAPI file for a minor version of an API that you want to import.
     
  2. When you get to the Review properties view, review the warning message that tells you which version your existing API is going to be replaced with.
     
  3. Click Import API.

     The existing API is overwritten with the newly imported API on the Applications and APIs page and the version is displayed only if it is 2.0.0 or later. When you add an action for the updated API to a flow, you can also see the updated version in the flow editor.

     

Importing an OpenAPI document into App Connect Designer 12.0.7.0-r2 through 12.0.10.0-r1

Complete these steps to add an imported API to App Connect:

1. From the App Connect Applications and APIs page, click the Import connector or API icon [+].
   
2. Complete the Import connector or API panel as follows:
   1. From the "Import document" view, select OpenAPI from the Document type list.
   2. Specify the file that you want to import. The file can be in a local or network drive, and can have any of these file extensions: .json, .yaml, or .yml. You can either drag the file from its location in an open file browser into the boxed area, or click within the boxed area to open a file browser and locate the file. The file name is displayed in the Import field, as shown in the following example.
      
   3. Click Next.
   4. From the "Review properties" view, complete the fields as follows:
      • Name: Specify a unique name of up to 30 characters by which your API can be identified on the Applications and APIs page or within the flow editor.
      • Description: Summarize the function of the API. The description is taken from the description property in the imported file if one exists, but you can update this field as required. Up to 250 characters are allowed.

      The defined operations in the imported file are displayed as actions. For information about how these actions are grouped, see OpenAPI document guidelines.

      
3. Click Import API. Your API is displayed on the Applications and APIs page with a Not connected status.

   You can expand the API to view the available actions. To use these actions in your flows, you'll need to specify account credentials as described in Connecting App Connect to your imported API (App Connect Designer instance in a containerized environment).

   

Importing an OpenAPI document into App Connect Designer 12.0.1.0-r1 through 12.0.7.0-r1

Complete these steps to add an imported API to App Connect:

1. From the App Connect Applications and APIs page, click the APIs tab.
2. Click the Add API icon [+].
   
3. Complete the Add an API panel as follows:
   1. From the "Import OpenAPI document" view, specify the file that you want to import. The file can be in a local or network drive, and can have any of these file extensions: .json, .yaml, or .yml. You can either drag and drop the file from its location in an open file browser into the boxed area, or click within the boxed area to open a file browser and locate the file. You'll see the file name in the boxed area, as shown in the following example.
      
   2. Click Next.
   3. From the "Review properties" view, complete the fields as follows:
      • Name: Specify a unique name of up to 30 characters by which your API can be identified on the APIs tab on the Applications and APIs page, or within the flow editor.
      • Description: Summarize the function of the API. The description is taken from the description property in the imported file if one exists, but you can update this field as required. Up to 250 characters are allowed.

      The defined operations in the imported file are displayed as actions. For information about how these actions are grouped, see OpenAPI document guidelines.

      
4. Click Add API. Your API is displayed on the APIs tab and is tagged with an imported label and a community icon that you can click to reveal additional details.

   You can expand the API to view the available actions. To use these actions in your flows, you'll need to specify account credentials as described in Connecting App Connect to your imported API (App Connect Designer instance in a containerized environment).

   

Importing an OpenAPI document into App Connect Designer 11.0.0.12-r1 or earlier

Complete these steps to add an imported API to App Connect:

1. From the App Connect Applications and APIs page, click the APIs tab.
2. If necessary, scroll to the bottom of the tab, and then click the Add your API now link.
3. From the Add an API panel, specify the file that you want to import. The file can be in a local or network drive, and can have any of these file extensions: .json, .yaml, or .yml. You can either drag and drop the file from its location in an open file browser into the boxed area, or click within the boxed area to open a file browser and locate the file. You'll see the file name in the boxed area, as shown in the following example.
   
4. Specify a unique name of up to 30 characters by which your API can be identified on the APIs tab on the Applications and APIs page, or within the flow editor.
5. Add a description that summarizes the function of the API.
6. Click Add API. Your API is displayed on the APIs tab and is tagged with an imported label .

   You can expand the API to view the available actions. To use these actions in your flows, you'll need to specify account credentials as described in Connecting App Connect to your imported API (App Connect Designer instance in a containerized environment).