How to use IBM App Connect with APIs imported from OpenAPI documents

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.

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 is referenced in the OpenAPI document that was imported into App Connect.

Availability:

Local connector in containers (Continuous Delivery release) 11.0.0.10-r1 or later
Local connector in containers (Extended Update Support release)
Local connector in containers (Long Term Support release)

The following information describes how to use IBM App Connect to connect an imported API to your other applications.

A business scenario
What to consider first
OpenAPI document guidelines
Restrictions
Importing an OpenAPI document into App Connect as an API
Connecting App Connect to your imported API
Using an imported API in a flow
Presentation of request fields in an action node in a flow
Responses and error case handling for flows
Removing an imported API from the App Connect catalog

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 to consider first

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)
Next, 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
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. 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.

OpenAPI Specification version

The document must conform to the OpenAPI Specification Version 2.0 or 3.0.x.

Restriction: If you are working in a containerized environment and the version of your App Connect Designer instance is between 11.0.0.10-r1 and 11.0.0.12-r1, only the OpenAPI Specification Version 2.0 is supported.

OpenAPI document formats

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 a value such as 2.0 or 3.0.1.
Ensure that the info properties provide the required metadata about the API.
Ensure that the paths properties are populated with the available endpoints and operations (including applicable parameters and expected responses) for the API.
Ensure that the host property (OpenAPI 2.0) or servers property (OpenAPI 3.0.x) is set to the name of the host or the IP address that serves the API.

HTTP methods

Operations that use the GET, POST, PUT, PATCH, DELETE, and HEAD HTTP methods are supported.

x-ibm-endpoints extension property

If the host or servers 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

Operation modeling in App Connect Designer 11.0.0.10-r1 to 11.0.0.12-r1

If you are using a version of App Connect Designer between 11.0.0.10-r1 and 11.0.0.12-r1 in a containerized environment, the defined operations are modeled 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.

Operation modeling by using x-ibm-conventions 0.0.1 standards

Note: This information is applicable if you are using App Connect Designer 12.0.1.0-r1 or later in a containerized environment, and want to comply with version 0.0.1 of the x-ibm-conventions standards.

Version 0.0.1 of the x-ibm-conventions extension enables you to use IBM-defined standards to determine whether operations in an OpenAPI document are grouped by tag name, path, or object when they are imported into App Connect. If the x-ibm-conventions extension is not declared in the OpenAPI document, or the OpenAPI definition does not comply with the x-ibm-conventions 0.0.1 standards, the operations will assume a default grouping and presentation format when imported into App Connect.

The defined operations are modeled into actions for the imported API, and are processed as follows:

The value of the operationId property is typically used as the action name.
The actions are grouped as follows:
- If the OpenAPI document contains the x-ibm-conventions 0.0.1 extension within the info object and the operationId property for all operations is in the format verb_model (for example, create_employee), the actions are grouped by model name (or object type) and the action name is shown as the verb in the operationId value.
- If the OpenAPI document does not contain the x-ibm-conventions 0.0.1 extension or the operationId property for all operations is not in the format verb_model, the actions are grouped by tag name.
- If all operations in the OpenAPI document contain tags, the actions are grouped by tag name.
- If operations in the OpenAPI document contain multiple tags, an action is grouped under each individual tag that is assigned to the corresponding operation.
- If none of the preceding conditions apply, the actions are grouped by operation path as defined within the paths object in the OpenAPI document.

Operation modeling by using x-ibm-conventions 0.0.2 standards

Note: This information is applicable only if using App Connect Designer 12.0.1.0-r4 or later in a containerized environment.

Conventions represent a set of IBM-defined standards for App Connect, which you can follow if writing a new OpenAPI document from scratch. You can apply these standards while creating the document, to configure a presentation format for your operations when imported into App Connect. Conventions are versioned and are declared using the x-ibm-conventions extension. Version 0.0.2 enables you to model operations in your OpenAPI document so that they are presented in a similar format as the objects and actions for applications in the App Connect Catalog when those operations are imported. Version 0.0.2 also applies changes to the request and response payloads to make them similar to the payloads for applications.

To comply with the x-ibm-conventions 0.0.2 standards, the following rules apply:

Declare the x-ibm-conventions extension within the info object in the OpenAPI document, and set the version to 0.0.2; for example:
```
"x-ibm-conventions": "0.0.2"
```
In the paths section of the OpenAPI document, ensure that each operation contains an operationId property in the following format:
```
"operationId": "verbName_objectName",
```
Define the operationId setting as follows:
- verbName can be any of these verbs (case-insensitive):
  - CRUD verbs: Create, Retrieve, RetrieveAll, Update, UpdateAll, Delete, DeleteAll, or UpdateOrCreate
  - A value of custom if defining a custom operation
- objectName represents the name of a model (or object) with an optional suffix. Use the plural form for the objectName value (case-insensitive); for example, Boards, pets, or Inventories.
  If you need to establish uniqueness for your operationId values, you can specify the objectName value in the format model_suffix, where suffix represents a unique text value. For example, to distinguish between two RetrieveAll operations for model pet, you can set objectName to pets for an operation to retrieve all pets by status, and then set objectName to pets_byTag for an operation to retrieve all pets by tags.
The following examples illustrate operationId settings for a Create operation on model board, and a custom operation on model pet:
```
"operationId": "create_Boards", 
```
```
"operationId": "custom_pets",
```
The following examples illustrate operationId settings for two RetrieveAll operations on model pet.
```
"operationId": "retrieveall_pets",
```
```
"operationId": "retrieveall_pets_byTag",
```
Note: When you import the OpenAPI document into App Connect, the object names are derived as follows:
- The objectName value (model name only) is used as an object name under which related actions are grouped. If objectName includes a suffix (which is appended to the model name), that suffix is ignored.
  If the plural form is not consistently used for a specific model name in the objectName values, when you import the OpenAPI document, both singular and plural forms of the object name will be shown in App Connect (for example, Board and Boards). The associated actions will be grouped under the singular or plural object name.
- The object names are presented in "Sentence case" format.
- The object names are listed alphabetically.
For each operation, define values for the summary and description properties as follows:
- Use the summary property to specify a short meaningful name for the action that will be shown in App Connect; for example, Send email.
```
"summary": "actionName",
```
- Use the description property to provide a short meaningful description that will be displayed below the action name in App Connect; for example, Compose and send an email.
```
"description": "helpfulDescription",
```
Note: When you import the OpenAPI document into App Connect, the action names are derived as follows:
- Under each object grouping, the relevant summary values are displayed as action names.
- Under each action name, the description value for the associated summary is displayed.
- The action names and descriptions are presented as specified in the OpenAPI document.

Non-compliance with the x-ibm-conventions 0.0.2 standards

If the OpenAPI document does not contain the x-ibm-conventions 0.0.2 extension, when you import the document into App Connect, the actions are grouped by tag name or path instead of object name, and the operationId value is displayed as the action name.
If the OpenAPI document contains the x-ibm-conventions 0.0.2 extension, but does not fully comply with the0.0.2 standards, a warning is typically provided to identify the non-compliant operations (by operationId). For example, you might see this warning if any operation does not contain an operationId setting in the required verbName_objectName format, or if any operation does not have a summary or description value.
If you proceed to import the OpenAPI document without fixing the non-compliant operations, the actions are grouped by tag name or path instead of object name in App Connect, and the operationId value is displayed as the action name.

Operation modeling by using x-ibm-annotations 0.0.2 standards

Note: This information is applicable only if using App Connect Designer 12.0.1.0-r4 or later in a containerized environment.

Annotations represent a set of IBM-defined standards for App Connect, which you can apply to an existing OpenAPI document to configure a presentation format for the operations that are imported into App Connect. Annotations are versioned and are declared using the x-ibm-annotations extension. The starting version of 0.0.2 enables you to model operations in your OpenAPI document so that they are presented in a similar format as the objects and actions for applications in the App Connect Catalog when imported. Version 0.0.2 also applies changes to the request and response payloads to make them similar to the payloads for applications.

To comply with the x-ibm-annotations 0.0.2 standards, the following rules apply:

Declare the x-ibm-annotations extension within the info object in the OpenAPI document, and set the version to 0.0.2; for example:
```
"x-ibm-annotations" : "0.0.2"
```
In the paths section of the OpenAPI document, ensure that each operation contains an x-ibm-operation property with a nested key/value pair for action and model in the following format.
```
 "operationId": "uniqueValue",
 "x-ibm-operation": {
  "action": "verbName",
  "model": "objectName"
 }, 
```
Note that existing operationId settings are not honored as part of the standards.

Define the x-ibm-operation settings as follows:
- For action, the verbName value can be any of these verbs (case-insensitive):
  - CRUD verbs: Create, Retrieve, RetrieveAll, Update, UpdateAll, Delete, DeleteAll, or UpdateOrCreate
  - A value of custom if defining a custom operation
- For model, use the plural form for the objectName value; for example, Boards, pets, or Inventories.
The following example illustrates how to specify the plural form for an objectName value in an OpenAPI document that defines a model named board:
```
 "operationId": "create_Board",
 "x-ibm-operation": {
  "action": "create",
  "model": "Boards"
 },
```
Note: When you import the OpenAPI document into App Connect, the object names are derived as follows:
- The objectName value of model is used as an object name under which related actions are grouped. If the plural form is not consistently used for each unique objectName value in the imported OpenAPI document as recommended, both singular and plural forms of the object name will be shown in App Connect (for example, Board and Boards), and the associated actions will be grouped under the singular or plural object name.
- The object names are presented in "Sentence case" format.
- The object names are listed alphabetically.
For each operation, define values for the summary and description properties as follows:
- Use the summary property to specify a short meaningful name for the action that will be shown in App Connect; for example, Send email.
```
"summary": "actionName",
```
- Use the description property to provide a short meaningful description that will be displayed below the action name in App Connect; for example, Compose and send an email.
```
"description": "helpfulDescription",
```
Note: When you import the OpenAPI document into App Connect, the action names are derived as follows:
- Under each object grouping, the relevant summary values are displayed as action names.
- Under each action name, the description value for the associated summary is displayed.
- The action names and descriptions are presented as specified in the OpenAPI document.

Non-compliance with the x-ibm-annotations 0.0.2 standards

If the OpenAPI document does not contain the x-ibm-annotations 0.0.2 extension, when you import the document into App Connect, the actions are grouped by tag name or path instead of object name, and the operationId value is displayed as the action name.
If the OpenAPI document contains the x-ibm-annotations 0.0.2 extension, but does not fully comply with the 0.0.2 standards, a warning is typically provided to identify the non-compliant operations (by operationId). For example, you might see this warning if any operation does not contain an x-ibm-operation setting with the required action and model values, or if any operation does not have a summary or description value.
If you proceed to import the OpenAPI document without fixing the non-compliant operations, the actions are grouped by tag name or path instead of object name in App Connect, and the operationId value is displayed as the action name.

Restrictions

OpenAPI Specification version

The OpenAPI Specification Version 3.1 isn't supported, so an import will fail for OpenAPI documents that are compliant with this version.

Exception: If you are working in a containerized environment and the version of your App Connect Designer instance is between 11.0.0.10-r1 and 11.0.0.12-r1, OpenAPI Specification Version 3.0 or later isn't supported.

Restrictions applicable to OpenAPI Specification Version 3.0.x only

The following restrictions are specific to documents that conform to the OpenAPI Specification Version 3.0.x only:

If multiple servers are described by using the servers property, only the first server configuration (url/description) will be used to make API calls. If required, update the server configuration in your OpenAPI document to identify your preferred target server before you import the file into App Connect.
Additionally, OpenAPI documents that include these definitions cannot be imported into App Connect:
- Variables are not supported for use with the servers property.
- Callback definitions are not supported for operations.
- Link definitions within a links section are not supported in operation responses.
- The use of anyOf or oneOf to specify alternative schemas for media types is not supported in the request body (requestBody section) of operations.
- The use of anyOf or oneOf to specify alternative schemas for media types is not supported in the response body (responses section) of operations.
- The use of anyOf or oneOf to combine schemas is not supported in operation parameters (parameters section).

File size limitation

In App Connect in containers (Continuous delivery operands 12.0.2.0-r2 or later), you cannot import OpenAPI documents that are larger than 3MB.
In App Connect in containers (Continuous delivery operands 12.0.2.0-r1 or earlier and Extended User Support), 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

App Connect Designer in a containerized environment:
- Where authentication is required, you can call only APIs that are secured with the following authentication types: basic, bearer, API key (single or multiple keys), OAuth 2.0 Password, and OAuth 2.0 Credentials.
- If the security scheme for the API or all its operations is set to an unsupported authentication type, the import of the OpenAPI document will fail. If a subset of the operations is secured using an unsupported authentication type, those operations will not be modeled into actions for the imported API.

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.
It is assumed that the API can consume or produce MIME types with a subtype of json only.

Parameter types and path parameter values

For OpenAPI 2.0, the following parameter types (specified using the in property) are supported: body, header, query, and path.
For OpenAPI 3.0.x, the following parameter types (specified using the in property) are supported: requestBody, header, query, cookie, 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 (OpenAPI 2.0) or requestBody (OpenAPI 3.0.x) 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

A flow that contains an imported API can be exported and re-imported into the same App Connect instance; for example, for backup and restore purposes. However, there's no support for sharing such flows (using export/import) with other instances.

Importing an OpenAPI document into App Connect as an API

The step for importing an OpenAPI document into App Connect as an API depend on which type of connector you want to use to run the defined API operations:

If you are using the local OpenAPI connector in an App Connect Designer instance in a containerized environment, see Importing an OpenAPI document into App Connect as an API (App Connect Designer instance in a containerized environment).

Connecting App Connect to your imported API

The steps for connecting App Connect to your imported API depend on which type of connector you want to use to run the defined API operations:

If you are using the local OpenAPI connector in an App Connect Designer instance in a containerized environment, see Connecting App Connect to your imported API (App Connect Designer instance in a containerized environment).

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.

Presentation of request fields in an action node in a flow

Compliance with the x-ibm-conventions 0.0.2 or x-ibm-annotations 0.0.2 standards

Note: This information is applicable only if using App Connect Designer 12.0.1.0-r4 or later in a containerized environment.

If the x-ibm-conventions 0.0.2 or x-ibm-annotations 0.0.2 standards were followed in the imported OpenAPI document, when you add an action node to a flow, the field names are derived from the name values that are assigned to the operation's parameters (or schema objects). The fields are typically structured as follows:

If parameters are passed in the request body of the operation, the action node displays the fields in a nested structure whose root node is named after the App Connect object that the action is grouped under.
Where relevant, fields are also displayed for any header, query, path, or cookie parameters (above any request body fields).

Example: Structure of multiple request body fields in an action node in an App Connect flow

The following examples show the requestBody or parameters settings for an operation in an imported OpenAPI document. The settings contain an internal reference (using $ref) to a schema.

x-ibm-conventions example for requestBody:

 "/user": {
"post": {
  "tags": [
 "user"
  ],
  "summary": "Create user",
  "description": "This can only be done by the logged in user.",
  "operationId": "create_users",
  "requestBody": {
 "description": "Created user object",
 "content": {
"application/json": {
  "schema": {
 "$ref": "#/components/schemas/User"
  }
},
"application/xml": {
  "schema": {
 "$ref": "#/components/schemas/User"
  }
},
"application/x-www-form-urlencoded": {
  "schema": {
 "$ref": "#/components/schemas/User"
  }
}
 }
  },
  "responses": {
...

x-ibm-annotations example for parameters:

  "/user": {
"post": {
 "tags": [
  "user"
 ],
 "summary": "Create user",
 "description": "This can only be done by the logged in user.",
 "operationId": "createUser",
 "x-ibm-operation": {
  "action": "create",
  "model": "users"
 },
 "consumes": [
  "application/json"
 ],
 "produces": [
  "application/json",
  "application/xml"
 ],
 "parameters": [
  {
"in": "body",
"name": "body",
"description": "Created user object",
"required": true,
"schema": {
 "$ref": "#/definitions/User"
}
  }
 ],
 "responses": {
...

The following example shows the resulting action node with nested fields under the object name.

Example of nested fields in an action node in an App Connect flow

Example: Structure of a single path parameter field in an action node in an App Connect flow

The following examples show the parameters settings for an operation in an imported OpenAPI document. The settings define a single path parameter with no request body.

x-ibm-conventions example:

 "/store/order/{orderId}": {
"get": {
  "tags": [
 "store"
  ],
  "summary": "Find purchase order by ID",
  "description": "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
  "operationId": "retrieve_orders",
  "parameters": [
 {
"name": "orderId",
"in": "path",
"description": "ID of order that needs to be fetched",
"required": true,
"schema": {
  "type": "integer",
  "format": "int64"
}
 }
  ],
  "responses": {
...

x-ibm-annotations example:

  "/store/order/{orderId}": {
"get": {
 "tags": [
  "store"
 ],
 "summary": "Find purchase order by ID",
 "description": "For a valid response try integer IDs with value >= 1 and <= 10.",
 "operationId": "getOrderById",
 "x-ibm-operation": {
  "action": "retrieve",
  "model": "orders"
 },
 "produces": [
  "application/json",
  "application/xml"
 ],
 "parameters": [
  {
"name": "orderId",
"in": "path",
"description": "ID of pet that needs to be fetched",
"required": true,
"type": "integer",
"maximum": 10,
"minimum": 1,
"format": "int64"
  }
 ],
 "responses": {
...

The following example shows the resulting action node with a single path parameter field. A request body or other parameters were not defined, so no additional fields are shown.

Example of a single field in an action node in an App Connect flow

Non-compliance with the x-ibm-conventions 0.0.2 or x-ibm-annotations 0.0.2 standards

Note: This information is applicable if using App Connect Designer in a containerized environment.

If the x-ibm-conventions 0.0.2 or x-ibm-annotations 0.0.2 standards are not supported or were not followed, when you add an action node for an imported API to a flow, the input field names are derived from the name values that are assigned to the operation's parameters (or schema objects). The fields are typically structured as follows:

If parameters are passed in the request body of the operation, the action node displays the fields in a nested structure whose root node is given a generic name of body.
Where relevant, fields are also displayed for any header, query, path, or cookie parameters (above any request body fields).

Example: Structure of multiple request body fields in an action node in an App Connect flow

The following example shows the parameters settings for an operation in an imported OpenAPI document. The settings contain an internal reference (using $ref) to a schema.

  "/user":
 post:
tags:
- user
summary: Create user
description: This can only be done by the logged in user.
operationId: createUser
produces:
- application/xml
- application/json
parameters:
- in: body
  name: body
  description: Created user object
  required: true
  schema:
 "$ref": "#/definitions/User"
responses:
  default:
 description: successful operation
...

The following example shows the resulting action node with nested fields under the object name.

Example: Structure of a single path parameter field in an action node in an App Connect flow

The following example shows the parameters settings for an operation in an imported OpenAPI document. The settings define a single path parameter with no request body.

  "/store/order/{orderId}":
 get:
tags:
- store
summary: Find purchase order by ID
description: For valid response try integer IDs with value >= 1 and <= 10. Other
  values will generated exceptions
operationId: getOrderById
produces:
- application/xml
- application/json
parameters:
- name: orderId
  in: path
  description: ID of pet that needs to be fetched
  required: true
  type: integer
  maximum: 10
  minimum: 1
  format: int64
responses:
  '200':
...

The following example shows the resulting action node with a single path parameter field. A request body or other parameters were not defined, so no additional fields are shown.

Responses and error case handling for flows

Compliance with the x-ibm-conventions 0.0.2 or x-ibm-annotations 0.0.2 standards

Note: This information is applicable only if using App Connect Designer 12.0.1.0-r4 or later in a containerized environment.

If the x-ibm-conventions 0.0.2 or x-ibm-annotations 0.0.2 standards were followed in the imported OpenAPI document, the following response and error handling details apply for imported operations (App Connect actions) in a flow:

When started, the flow will continue on any 2xx (Success) HTTP status codes that are defined in the OpenAPI document, but if the API returns a non-2xx HTTP status code for an action, the flow will fail with an error.
The response parameters that are returned for any 2xx (Success) status codes are available for mapping within subsequent nodes in the flow if required, by using the Available mappings list. In this list, the response for an action node is assigned a name that is formed from the operationId value suffixed with _model.
- If the response includes headers, the response body parameters are nested under the model (or object) name; otherwise, the body parameters are shown at the top level.
  - The following example shows a response definition that includes headers and a body in an imported OpenAPI document.
    
    "responses": { "200": { "description": "successful operation", "headers": { "X-Rate-Limit": { "description": "calls per hour allowed by the user", "schema": { "type": "integer", "format": "int32" } }, "X-Expires-After": { "description": "date in UTC when toekn expires", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/xml": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid username/password supplied" } }
    
    The following example illustrates how the response is presented in the Available mappings list in App Connect. The header parameters are displayed at the same (top) level as the body parameter, which in this case is of type string and therefore exhibits no nesting. The header parameters are displayed above the body parameter.
  - The following example shows a response definition that includes a body only in an imported OpenAPI document.
    
    "responses": { "200": { "description": "successful operation", "content": { "application/xml": { "schema": { "$ref": "#/components/schemas/User" } }, "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "description": "Invalid username supplied" }, "404": { "description": "User not found" } }
    
    The following example illustrates how the response is presented in the Available mappings list in App Connect.
- If the response is an array, the response parameters are nested under the model (or object) name.
  - The following example shows a response definition of type array in an imported OpenAPI document.
    
    "responses": { "200": { "description": "successful operation", "content": { "application/xml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Pet" } } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Pet" } } } } }, "400": { "description": "Invalid status value" } },
    
    The following example illustrates how the response array is presented in the Available mappings list in App Connect.
The response status code that is returned for an OpenAPI action is available for mapping within subsequent nodes in the flow if required.

Non-compliance with the x-ibm-conventions 0.0.2 or x-ibm-annotations 0.0.2 standards

Note: This information is applicable if using App Connect Designer in a containerized environment.

If the x-ibm-conventions 0.0.2 or x-ibm-annotations 0.0.2 standards are not supported or were not followed in the imported OpenAPI document, the following response and error handling details apply for imported operations (App Connect actions) in a flow:

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. The content of an entry is structured by status code, as provided in the OpenAPI document. An entry 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.
- The following example shows a response definition that includes headers and a body in an imported OpenAPI document.
  "responses": { "200": { "description": "successful operation", "headers": { "X-Rate-Limit": { "description": "calls per hour allowed by the user", "schema": { "type": "integer", "format": "int32" } }, "X-Expires-After": { "description": "date in UTC when toekn expires", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/xml": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid username/password supplied" } }
  The following example illustrates how the response is presented in the Available mappings list in App Connect. The header and body parameters are nested within the status code, and the header parameters are displayed above the body in the nested structure.
- The following example shows a response definition that includes a body only in an imported OpenAPI document.
  "responses": { "200": { "description": "successful operation", "content": { "application/xml": { "schema": { "$ref": "#/components/schemas/User" } }, "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "description": "Invalid username supplied" }, "404": { "description": "User not found" } }
  The following example illustrates how the response is presented in the Available mappings list in App Connect. The body parameters are nested within the status code.
- The following example shows a response definition of type array in an imported OpenAPI document.
  "responses": { "200": { "description": "successful operation", "content": { "application/xml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Pet" } } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Pet" } } } } }, "400": { "description": "Invalid status value" } },
  The following example illustrates how the response array is presented in the Available mappings list in App Connect. The parameters are nested within the status code.
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 Catalog page.

If using App Connect Designer 12.0.7.0-r2 or later in a containerized environment, go to the Catalog page and then click the Remove this API link for the API. The API should be located in the Not connected list.
If using App Connect Designer 12.0.7.0-r1 or earlier in a containerized environment, go to the APIs tab on the Catalog page and then click the Remove this API link for that API.

The Remove this API 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 Managing flows.