Setting API properties

In addition to the pre-supplied API properties that you can use to control the behavior of API Connect policies, you can define your own API properties. The properties that you define can be referenced in your API definitions.

About this task

  • This task relates to configuring an OpenAPI 3.0 API definition. For details on how to configure an OpenAPI 2.0 API definition, see Editing an OpenAPI 2.0 API definition.
  • OpenAPI 3.0 APIs are supported only with the DataPower® API Gateway, not with the DataPower Gateway (v5 compatible).
  • For details of current OpenAPI 3.0 support limitations, see OpenAPI 3.0 support in IBM® API Connect.

You can complete this task either by using the API Designer UI application, or by using the browser-based API Manager UI.

API properties include property name, value, and, optionally a specific Catalog to which a property value applies. For a list of pre-supplied API properties relating to various policies, see API properties.
Note: Once defined, an API property is read only.

For information on how to reference a property in an API definition, see Variable references in API Connect.

It is also possible to define properties that are specific to a Catalog and can be referenced by any of the APIs in that Catalog; for more information, see Creating and configuring Catalogs. Note that if you define a Catalog property of the same name as an API property, the API property takes precedence over the Catalog property.

At any time, you can switch directly to the underlying OpenAPI YAML source by clicking the Source icon OpenAPI Source icon. To return to the design form, click the Form icon Form icon.

Tip: If you add or change an API property on an API that is already staged or published, you must re-stage or re-publish the Product that contains the updated API for the change to take effect.


  1. Open the API for editing, as described in Editing an OpenAPI 3.0 API definition.
  2. Select the Gateway tab, expand Gateway and portal settings then, if there are already one or more API properties defined, expand Properties.
  3. Configure an API property.
    • To define a new API property, complete the following steps:
      1. Click the add icon OpenAPI 3.0 API add icon alongside Properties in the navigation pane.
      2. Provide the following information:
        • Property Name: Enter a name for the property; this name is used to reference the property. The following character set is supported for the Name of an API property: [A-Za-z0-9_-]+. Spaces are allowed.
        • Value: A default value for the property. Leave blank if the property is to have a null vale by default.
        • Description: An optional description of the property. You can use CommonMark syntax for rich text representation.
        • Select Encoded if you want to hide the property values, or protect user passwords from casual observance.
          Note: If you encode a property value, it is saved in Base64 encoded form; it is not encrypted. If you subsequently clear the Encoded check box, the original property value is restored in its unencoded form.
      3. Click Create.
    • To modify an existing API property, click the property name in the navigation pane. You can then change any of the configuration settings.
  4. Click Save to save your changes.

What to do next

Optionally, define a value for the property that is specific to a particular Catalog; see Defining Catalog specific property values.