Defining servers for a Path

Server definitions for a Path provide alternative target servers when calling the API at that Path.

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.

Note: It is unlikely that you will need to define servers for a Path because it applies only if the API operations are distributed across different gateway endpoints, and such a configuration is possible only if you are hosting your API operations on your own runtime endpoints outside of API Connect. For an API that is published to the DataPower API Gateway, all API operations are invoked on the same gateway service.

A server defined for a Path overrides any server defined for the parent API. 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 by clicking the Source icon OpenAPI Source icon . To return to the design form, click the Form icon Form icon .

Procedure

Open the API for editing, as described in Editing an OpenAPI 3.0 API definition.
Expand Paths.
Expand the required Path, then, if there already one or more servers defined for the Path, expand Servers.
To create a new server definition for the Path, click the add icon alongside Servers under the Path in the navigation pane. To edit an existing server definition, click the server URL under the Path 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.