IBM extensions to the OpenAPI specification

You use the x-ibm-configuration object in your OpenAPI definition file to add extensions that are specific to IBM® API Connect.

The x-ibm-configuration extension has the following structure:

  enforced: enforced_boolean
  phase: Phase
  testable: test_boolean
    enabled: cors_boolean
      - assembly_component
  gateway: gateway_type
  type: api_type

The following table lists the various extensions used by API Connect, whether they are required, a description of their use and behavior, and their type.

Table 1. IBM extensions
Extension Required Description Type
phase Yes Use the phase extension to describe the maturity of the API. It can take the following values:
  • identified: the API is in the early conceptual phase and is neither fully designed nor implemented.
  • specified: the API has been fully designed and passed an internal milestone but has not yet been implemented.
  • realized: the API is in the implementation phase.
testable Yes Use the testable extension to specify whether the API can be tested using the test tool in the Developer Portal. Boolean
enforced Yes Use the enforced extension to specify if the API Connect gateway is used to enforce the API.
  • true indicates that the API Connect gateway is used to enforce the API.
  • false indicates that the API Connect gateway is not used to enforce the API.
cors Yes Use the cors extension to specify whether CORS access control is used for the API. The extension has an enabled field which is a Boolean. Object (with a single Boolean field)
DataPower API Gateway
onlyactivity-log No Use the activity-log extension to configure your logging preferences for the API activity that is stored in Analytics. The preferences that you specify will override the default settings for collecting and storing details of the API activity. Object
assembly No Use the assembly extension to describe the application of policies and logic to an API. It contains an execute field that contains an array of policies that are applied in order. It can contain a catch field that contains an array of error cases to be caught.

For information about use of the execute field, see execute.

For information about use of the catch field, see catch.

gateway No Use the gateway extension to specify which type of gateway you want to use. If you are using the DataPower® Gateway (v5 compatible) or DataPower API Gateway, it must be included and take one of the following values:
  • datapower-gateway (DataPower Gateway (v5 compatible))
  • datapower-api-gateway (DataPower API Gateway)

For information about types of gateways, see API Connect gateway types.

type No The type extension takes one of the following values:
  • rest
  • wsdl
properties No Use the properties extension to define properties for use in an API. Object (properties)
catalogs No Use the catalogs extension to define Catalog-specific values for properties defined in the properties extension. Object (catalogs)

The following example shows the x-ibm-extension section of an API that is enforced by API Connect, is in the realized state, is testable through the test tool in the Developer Portal, has CORS access control enabled, and has a simple assembly that invokes a URL and then redacts a field from the request or response.

  enforced: true
  phase: realized
  testable: true
    enabled: true
      - invoke:
          title: Example Invoke
          target-url: ''
          description: Example description
      - redact:
          - action: redact
              - request
              - response
            path: //*[@name='secondaryAddress']/*[@name='streetAddress']
      value: 1234
      description: An ID to be used for validating.
      encoded: false
        ID: 5678