IBM extensions to the OpenAPI specification

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

x-ibm-configuration:
  enforced: enforced_boolean
  phase: Phase
  testable: test_boolean
  cors:
    enabled: cors_boolean
  activity-log:
      activity_logging_extension
  assembly:
    execute:
      - assembly_component
  gateway: gateway_type
  type: api_type
  properties:
      properties_extension
  catalogs:
      catalogs_extension

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.	String
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.	Boolean
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)
activity-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.	Object
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.	String
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.

x-ibm-configuration:
  enforced: true
  phase: realized
  testable: true
  cors:
    enabled: true
  assembly:
    execute:
      - invoke:
          title: Example Invoke
          target-url: 'https://example.com/api'
          description: Example description
      - redact:
        actions:
          - action: redact
            from: 
              - request
              - response
            path: //*[@name='secondaryAddress']/*[@name='streetAddress']
  properties:
    ID:
      value: 1234
      description: An ID to be used for validating.
      encoded: false
  catalogs:
    Sandbox:
      properties:
        ID: 5678