Defining servers for an operation

Server definitions for an API operation provide alternative target servers when calling that operation.

About this task

Note:

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.

A server defined for an operation overrides any server defined for the parent API or Path. You can define more than one server but only the first is used by API Connect.

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

Procedure

Open the required API for editing, as described in Editing an OpenAPI 3.0 API definition.
Expand Paths, then expand the required Path.
Expand Operations, expand the required operation, then, if there already one or more servers defined for the operation, expand Servers.
To create a new server definition for the operation, click the add icon alongside Servers under the operation in the navigation pane. To edit an existing server definition, click the server URL under the operation in the navigation pane.
Provide the following information:
- Server URL (required): The specified URL is used to determine the full URL endpoint for the calling the API, taking into account any vanity endpoint configuration in the Catalog in which the API is published. For an API that is enforced by the DataPower API Gateway, the value entered here is interpreted as the basepath so you would typically provide only the basepath value; for example:
```
/my_basepath
```
  For full details on how the server URL is used to determine the full URL endpoint, see Configuring vanity endpoints for a Catalog.
- Server Description: An optional description of the host designated by the URL. You can use CommonMark syntax for rich text representation.
- Server Variables (available when editing an existing server definition): A server variable defines a map between a variable name and its value. The value is used for substitution in the server's URL template.
  1. To add a new server variable, click Add. To edit an existing server variable, click the variable name.
  2. Provide the following information:
    - Server Variable Name (required).
    - Default value (required).
    - An optional rich text description. You can use CommonMark syntax for rich text representation.
    - One or more Enum Value entries (available when editing an existing server variable). Enum values specify an enumeration of string values to be used if the substitution options are from a limited set. To add an new Enum value, click Add, enter the value, then click Create. To edit an existing Enum value, click the Enum value.
  3. If you are creating a new server variable, click Create. The server variable details are displayed for further editing.
  4. If required, use the breadcrumb trail to return to your server definition for further editing.
If you are creating a new server definition, click Create.
The path details are displayed for further editing as described in 5.
Click Save when done.