OpenAPI 3.0 support in IBM API Connect

IBM® API Connect supports the OpenAPI 3.0 specification, with some limitations. The current implementation includes complete support for the Berlin Group NextGen PSD2 requirements.

Overview

A Product can contain any combination of OpenAPI 2.0 and OpenAPI 3.0 APIs. When you publish a Product that contains an OpenAPI 3.0 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 APIs are validated.

You can also validate OpenAPI 3.0 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.

If you retrieve an API object by using the developer toolkit CLI or the API Connect REST APIs, there is an oai_version property that defines which OpenAPI version the API represents.

There is no OpenAPI 3.0 API support with the DataPower® Gateway (v5 compatible); OpenAPI 3.0 API support is provided by the DataPower API Gateway only.

Limitations

The limitations to the OpenAPI 3.0 support in API Connect are as follows:
User interface limitations
  • Some aspects of the OpenAPI 3.0 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 API Designer 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.0 API.
    • There is no support for callbacks or links, and APIs containing them will not be published.
    • The following constructs of Open API 3.0 are less commonly used, and are not supported:
      • allowEmptyValue
      • allowReserved
    • A parameter object cannot contain an explode keyword with a value of true.
    • A path or header parameter object must have or default the style keyword to simple.
    • A query parameter object must have or default the style keyword to form.
  • Assembly policies.
    • All policies are supported.
    • JSON schema support is limited to Draft 4 and earlier. Therefore, the following policies are limited to those drafts:
      • 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.
    • Security.
      • The OpenID Connect (OIDC) security scheme is not supported.
      • The use of cookies in an API key is not supported.