The OpenAPI Specification, previously known as the Swagger Specification, is a definition format for describing REST APIs. You can import OpenAPI documents that contain API definitions into IBM App Connect. Each imported document is added as an API to the App Connect catalog of applications and APIs, and can be used to call the API from a flow.

You can use App Connect to pass data between an imported API and other apps – automatically, in real time. You can do so using configuration and data mapping techniques (without any need for coding), and can achieve a return on your investment in minutes or hours, rather than days or months.

This guide shows you how.

Note: APIs that you add to your flows can be created by importing OpenAPI documents, or by discovering shared APIs that are managed natively in IBM Cloud. For more information about using shared APIs in App Connect, see How to use IBM App Connect with shared APIs in IBM Cloud.

Additional reference: For specific information about your imported API, see the site that hosts the API’s documentation. If provided, see also the externalDocs documentation that’s referenced in the OpenAPI document that was imported into App Connect.

If you can’t find what you want, or have comments about the “how to” information, please either add comments to the bottom of this page or .

A business scenario

The challenge

Your retail business has been growing steadily, but your current systems are antiquated and involve a number of manual processes. Although happy about the upturn in business, your Sales and Marketing teams are hampered by the time-intensive processes, and would like to more efficiently manage and track stock levels, monitor payments, and analyze trends.

To help automate your processes, you’ve created and published several REST APIs, including an inventory API, which are tailored to your business needs. These APIs can be invoked in the standard ways by using tooling such as cURL. However, you’d also like to provide a graphical user interface to these APIs so that Sales and Marketing can easily set up automations without needing to understand the technical aspects of APIs and how to interact with resources via endpoints.

How App Connect can help

Use App Connect to boost your inventory, purchasing, and reporting capability by exposing the operations and parameters of the inventory API in the UI so that your teams can specify query parameters for calls to the API and obtain responses they can act on.

You can save or download a copy of the OpenAPI document that describes the inventory API, and then import the file into App Connect as an API. The imported inventory API exposes the API’s operations as actions, and exposes associated parameters as fields. And because the inventory API’s operations and parameters were sensibly named, it’s easy for your Sales and Marketing teams to recognize the purpose of each action, and, with minimal training, to understand what the API offers. So it’s business as usual for your teams who are already familiar with the App Connect UI – they can use App Connect to create flows that integrate the inventory API with other apps.

So when a sales order is created, the Sales team can check the stock balance and raise notifications in App Connect or alerts in Slack if the balance has fallen below a certain level. Maybe they also want to raise purchase orders with your vendors to replenish your stock. And for overdue unpaid invoices, they might want to set up automated payment reminders. Or, your Marketing team might create flows to analyze your customers’ buying patterns and spending so they can offer promotions and suggestions, or flows to analyze trends so your buyers can determine which product lines are most popular and make informed decisions about future stock purchases.

What should I consider first?

  1. To use App Connect with an imported API, you must have an OpenAPI document that defines all the resources and operations of your REST API.
    More information: OpenAPI document guidelines (See also: Restrictions)
  2. Next, use the “Add an API or Web Service” panel to import the OpenAPI document into the App Connect catalog. The imported document is added as an API with a set of actions that you can use in App Connect.
    More information: Importing an OpenAPI document into App Connect as an API
  3. Finally, connect App Connect to the imported API so you can use it in your flows.
    More information: Connecting App Connect to your imported API

OpenAPI document guidelines

Use the following guidelines to help ensure that your OpenAPI document is well formed and meets the requirements for a successful import:

  • The document must conform to the OpenAPI Specification Version 2.0.
  • YAML and JSON formats are supported, and must be valid. You can use any of these file extensions: .json, .yaml, or .yml.
  • All required properties in the document must have a value specified. For example, ensure that the swagger property is set to “2.0”, that the info properties provide the required metadata about the API, and that the paths properties are populated with the available endpoints and operations (including applicable parameters and expected responses) for the API. Also ensure that the host property is set to the name of the host or the IP address that serves the API.
  • Operations that use the GET, POST, PUT, PATCH, DELETE, and HEAD HTTP methods are supported. The defined operations are modelled into actions for the imported API, and are processed as follows:
    • The value of the operationId property is used as the action name, so consider using a naming convention for the string values that helps identify the purpose of the action.
    • If operationID has an empty value or contains one of the following characters, a name is generated for the action:
      { } | \ ^ [ ] ` = ; / ? : @ & = + $ , .

      The generated action name is derived by combining the HTTP method and the operation path. For example:

      • POST /pet resolves to post_pet.
      • POST /user/createWithArray resolves to post_user_createWithArray.
      • GET /pet/{petId}/uploadImage resolves to get_pet__petId_uploadImage.
      • GET /store/order/{orderId} resolves to get_store_order__orderId.
    • The parameters defined for an operation are displayed as fields for the associated action. The name value is used for the field names.
  • If the host property is not set in the OpenAPI document, but an x-ibm-endpoints extension property is present, its endpointUrl value will be used. The following example shows this extension property:
    
    x-ibm-endpoints:
    - endpointUrl: https://api.eu.apiconnect.ibmcloud.com/johndoeibmcom-dev/sb
      type:
      - production
      - development
    
  • Before you import the document into App Connect, consider using an OpenAPI editor to review and validate the document, and fix any identified syntax errors.

Restrictions

OpenAPI Specification version
The OpenAPI Specification Version 3.0 isn’t supported, so an import will fail for OpenAPI documents that are compliant with this version.
File size limitation
In the App Connect UK environment, you cannot import OpenAPI documents that are larger than 500KB.
Remote or URL references to definitions
  • The API definition must be in a single OpenAPI document. Internal references (using $ref properties that start with #) are supported; for example:
    $ref: '#/definitions/User'
  • Remote or URL references to OpenAPI code that is defined in a separate file are not supported, and will cause the import to fail; for example:
    $ref: 'somedir/filename.yaml#/someElement'
    $ref: 'https://myhost.com/somedir/filename.yaml'
API schemes
Only the following schemes (or transfer protocols) are supported for an API or operation: http and https.
Authentication
  • Where authentication is required, you can call only APIs that are secured using basic authentication or a single API key.
  • OAuth2 isn’t supported.
  • If the security scheme for the API or all its operations is set to oauth2, the import of the OpenAPI document will fail. If a subset of the operations is secured using OAuth2, those operations will not be modelled into actions for the imported API.
  • Operations that require multiple API keys are not supported and will not be modelled into actions.

Tip: You can identify the non-compliant operations by reviewing your OpenAPI document to identify which operations do not have a corresponding action in App Connect.

Multipurpose Internet Mail Extensions (MIME) types
  • Only the following MIME types are supported:
    • MIME types with a subtype of json (that is, application/json and any “json” based custom vendor-specific MIME types)
    • text/plain

      All other MIME types, including a setting of */*, are not supported. Operations with a single unsupported MIME type definition will not be modelled into actions.

  • If no MIME types are defined for the consumes or produces property, it is assumed that the API can consume or produce MIME types with a subtype of json only.
Parameter types and path parameter values
  • The following parameter types (specified using the in property) are supported: body, header, query, and path.
  • The formData parameter type isn’t supported.
  • The primitive data type file isn’t supported.
  • The forward slash character (/) isn’t supported for path parameter values. For example, specifying a value of /genre/crime for the {film_path} path parameter from the following code results in encoded forward slashes in the query request URL – that is, films%2Fgenre%2Fcrime.
    
    /films{film_path}:
     get:
       parameters:
         - name: film_path
           in: path
           required: true
           type: string
           default: "/"
    
JSON schema
The OpenAPI Specification allows ‘definitions’ and body parameters to contain JSON schema. App Connect supports a subset of the JSON schema validation keywords, as identified below:

  • Validation keywords for any instance type:
    • Supported: type, enum
    • Ignored: const
  • Validation keywords for numbers: All ignored
  • Validation keywords for strings: All ignored
  • Validation keywords for arrays:
    • Supported: items
    • Ignored: All others
  • Validation keywords for objects:
    • Supported: properties, required
    • Ignored: All others

Composing schemas with conditional and boolean logic isn’t supported.

Export and import of flows
Flows that contain an imported API can be exported and imported by the same user; for example, for backup and restore purposes. However, there’s no support for sharing such flows (using export/import) with other users.

Importing an OpenAPI document into App Connect as an API

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

  1. From the App Connect Catalog page, click the APIs tab.
  2. If necessary, scroll to the bottom of the tab, and then click the Add your API or web service now link.
  3. From the “Add an API or Web Service” 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.

    OpenAPI document added to the 'Add an API or Web Service' panel

    Note: Specifying a file URL is applicable only if you are importing a SOAP web service. For more information, see How to use IBM App Connect with SOAP web services.

  4. Specify a unique name (up to 30 characters) by which your API can be identified on the APIs tab on the Catalog page or within the flow editor.
  5. Optional. Add a description that summarizes the function of the API.
  6. Click Add.

    Your API is displayed on the APIs tab and is tagged with an ‘imported’ label Imported label for APIs and web services. You can expand the API to view the available actions and can use these actions in your flows.

Connecting App Connect to your imported API

To create an integration flow that passes data between an imported API, and 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 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 imported API:

  1. To connect from the Catalog page:
    1. From the Catalog page, click the APIs tab. You’ll see a list of:

      Shared and imported APIs and web services on the APIs tab

    2. Locate and click the imported API.
    3. Click Connect to display the connection fields.
  2. To connect from the flow editor when adding the API as a target application:
    1. From the flow editor, go to the APIs tab and select the imported API.
    2. Select the action that you want to add.
    3. Click Connect to display the connection fields.
  3. 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 all three values.
    • Leave all the fields blank.
  4. 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 imported API. For information about setting up multiple accounts, see Managing accounts in App Connect.

Using an imported API in a flow

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

Responses and error case handling for flows

The following details apply for flows that include an imported API:

  • The flow will continue on any 2xx (Success) or non-2xx HTTP status codes that are defined in the OpenAPI document.
  • The response status code returned for an OpenAPI 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 OpenAPI document and then import it again. (Remember to first remove the current imported API from the App Connect catalog if you want to replace it.)
  • 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 OpenAPI document, 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.

Removing an imported API from the App Connect catalog

If no longer needed, you can delete an imported API from the APIs tab on the Catalog page by clicking the Remove this API link for that 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.

For information about deleting flows, see Starting, stopping, editing, viewing, sorting, and deleting flows. For information about removing accounts, see Managing accounts in App Connect.

Join The Discussion

Your email address will not be published. Required fields are marked *