OpenAPI 3.1 support in IBM API Connect

IBM® API Connect supports the OpenAPI 3.1 specification, with some limitations.

Overview

A Product can contain any combination of OpenAPI 2.0, OpenAPI 3.0, and OpenAPI 3.1 APIs. When you publish a Product that contains an OpenAPI 3.1 API, that API is validated to ensure that it is syntactically correct, and that references to configuration resources and policies resolve correctly, in the same way that OpenAPI 2.0 and OpenAPI 3.0 APIs are validated.

You can also validate OpenAPI 3.1 APIs in your local file system by using the apic validate command provided by the developer toolkit CLI; for details, see Validating the YAML or JSON definition of an API or Product.

Gateway support

OpenAPI 3.1 support varies by gateway type:

DataPower® API Gateway: The DataPower API Gateway supports publishing OpenAPI 3.1 APIs with JSON Schema draft-04.
DataPower Nano Gateway: The DataPower Nano Gateway supports publishing OpenAPI 3.1 APIs with JSON Schema 2020-12.
DataPower Gateway (v5 compatible): There is no OpenAPI 3.1 API support with the DataPower Gateway (v5 compatible).

Limitations

The limitations to the OpenAPI 3.1 support in API Connect are as follows:

User interface limitations

Some aspects of the OpenAPI 3.1 specification are not currently supported by the user interface. In such circumstances, use the OpenAPI source directly.
Validation errors that are identified locally are reflected in the API editor header almost immediately. However, some validation errors can be identified only by the API Manager backend and are not reflected until the API is saved; this means that, on saving an API, some validation errors might appear or disappear.
The user interface does not currently support referencing a request body component from the request body of an operation. If you want to reference a request body component, add the reference to the request body of the operation directly in the OpenAPI source:
```
requestBody:
  $ref: '#/components/requestBodies/request_body_component_name'
```
The reference is confirmed on the details page for the request body in the user interface however.
If, in the IBM API Studio user interface, you create and activate an API of the same name and version as one that has already been activated from the API Manager user interface, the Edit Rate Limit operation fails.

Limitations for APIs that are enforced by the DataPower API Gateway

To suppress the error message for the following limitations and publish the API, set the x-ibm-configuration.compatibility.suppress-limitation-errors property to true as shown in the following example:

compatibility:
  suppress-limitation-errors: true

Attention: Enabling suppress-limitation-errors merely disables the error messages so that the API can be published.

General limitations.
- The servers array cannot contain more than one server.
- The url entry in the servers array cannot contain variables.
- The path objects cannot contain server object overrides.
- There is no support for converting a WSDL defined SOAP service into an OpenAPI 3.1 API.
- There is no support for callbacks or links, and APIs containing them will not be published.
- External references ($ref pointing to other files) are not supported.
- The following constructs of OpenAPI 3.1 are less commonly used, and are not supported:
  - allowEmptyValue
  - allowReserved
Assembly policies.
- All policies are supported.
- JSON schema support is limited to Draft 4 and earlier for the DataPower API Gateway. The following policies are affected by JSON schema version support:
  - gatewayscript
  - set-variable
  - switch
  - json-to-xml
  - xml-to-json
  - parse
  - xslt
  - map
  - validate
  For detailed information about the Draft 4 and earlier specifications, see https://json-schema.org/specification-links.html#draft-4. For JSON Schema 2020-12, see http://json-schema.org/draft/2020-12/schema.
- Security.
  - The OpenID Connect (OIDC) security scheme is not supported.
  - The use of cookies in an API key is not supported.

Limitations for DataPower Nano Gateway

The DataPower Nano Gateway has the following specific limitations:

The url entry in the servers array cannot contain variables.
External references ($ref pointing to other files) are not supported.
Only the validate policy is affected by JSON schema version.
Only API key security schema is supported.