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 IBM 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
  • General limitations.
    • The servers array cannot contain more than one server.
    • The url entry in the servers array cannot contain variables.
    • path objects cannot contain server object overrides.
    • Wildcarding in response objects is not supported for error codes or success codes.
    • There is no support for converting a WSDL defined SOAP service into an OpenAPI 3.0 API.
  • Assembly policies.
    • Only the following policies are supported:
      • invoke
      • jwt-generate
      • jwt-validate
      • oauth
      • throw
      • user-security
    • The validate and map policies are not supported.
    • 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

      For draft specification details, see https://json-schema.org/specification-links.html.

    • Security.
      • The following security schemes are not supported:
        • HTTP JWT Bearer (HTTP Basic scheme is supported).
        • OAuth2 with multiple flows (a single flow is supported).
        • OpenID Connect (OIDC).
      • The use of cookies in an API key is not supported.