Referring to an extension in an API definition

To refer to an OpenAPI extension in your API definition YAML (or JSON) file, add an extensions key under x-ibm-configuration.

Before you begin

Add the OpenAPI extension to any Catalogs that the API is to be published to, by importing its definition file; for details, see Working with OpenAPI extensions. If the target Catalog does not contain the OpenAPI extension then attempts to publish the API to it will fail.

About this task

The following example shows an extension definition file that defines a bank branch, in YAML format:

extension: '1.0.0'

info: 
   title: Banking services
   name: banking
   version: 1.0.0
   description: Banking extensions
   contact: 
     name: IBM API Connect
     url: https://apiconnect.ibm.com/
     email: myname@ibm.com

portal-visible: true

properties:
  title: "Branch"
  type: "object"
  properties: 
    Branch type: 
      type: "string"
      enum: 
        - "ATM"
        - "Walk in"
    location: 
      type: "object"
      title: "Location"
      properties: 
        city: 
          type: "string"
          default: "San Francisco"
        state: 
          type: "string"
          default: "CA"
        citystate: 
          type: "string"
          description: "This is generated automatically from the previous two fields"
          template: "{{city}}, {{state}}"
          watch: 
            city: "location.city"
            state: "location.state"
  required:
    - Branch type

The following table provides more information on the available fields when creating an API extension.

Table 1. Description of the fields
Field	Description	Required	Default value	Example
`version`	Version number of the extension Note: The `version` field must follow the `version.release.modification` version numbering scheme.	Yes		`1.0.0`
`title`	Title of the extension Note: The `title` and `name` fields must be kept short so that they can be displayed in the API Manager user interface.	Yes		Banking service
`name`	Short name for the extension Note: The `name` field must be a single word and contain only alphanumeric characters, dash, and underscore characters.	Yes		banking
`description`	Short description of the extension	No		Banking extensions
`termsofservice`	Terms of service for the extension	No		Terms_of_Service
`license.name`	Name of the license	No		IBM API Connect
`license.URL`	URL to the license	No		https://apiconnect.ibm.com/
`contact.name`	Name of the contact	No		myname@ibm.com
`contact.URL`	URL for contacting the organization	No		https://www.example.com/support
`contact.email`	Email for contacting the organization	No		support@example.com
`portal`	Whether the extension is visible in the developer portal	No	`true`	`true` or `false`
`gateways`	List of gateways the extension can be used with Note: The `gateways` field is optional, but if included, it must list the types of gateways the extension can be used with.	No		`datapower-api-gateway` `datapower-gateway`
`properties`	The custom properties to be included in the OpenAPI extension.	No		The `properties` field can be customized to include any valid OpenAPI properties. `properties: title: "Branch" type: "object" properties: Branch type: type: "string" enum: - "ATM" - "Walk in"`

Procedure

To enable the use of custom extensions in an API definition, complete the following steps:

Edit the API definition YAML file and add the reference. For example:

x-ibm-configuration:
      .
      .
      .
  extensions:
    banking: 1.0.0

In your API definition file, add a property whose name must begin with x- and references the name of the extension you created. Specify the values of the properties that were defined in the OpenAPI extension YAML file.
The following example uses the banking extension:
```
      .
      .
      .
x-banking:
  Branch type: ATM
  location:
    city: San Francisco
    state: CA
    citystate: 'San Francisco, CA'
  
```