Dynamic Routing

Edit online

This policy enables webMethods API Gateway to support dynamic routing of virtual aliases based on policy configuration. The configured policies are enforced on the request sent to an API and these requests are forwarded to the dynamic endpoint based on specific criteria that you specify.

Note: As the dynamic routing policy's capabilities can also be configured using conditional routing policy, the dynamic routing policy will be deprecated in future releases and the configurations will be migrated to conditional routing policy. Hence, IBM recommends to use conditional routing policy over dynamic routing policy. In future version, when dynamic routing is migrated to conditional routing policy ${sys:dyn_Endpoint} will be replaced with ${dynamicEndpoint} system variable.
The table lists the properties that you can specify for this policy:
Property Description
Route To. Specifies the URLs of two or more native services in a pool to which the requests are routed.
Endpoint URI Specifies the URI of the native API endpoint to route the request to in case all routing rules evaluate to False. Service registries that have been added to the API Gateway instance are also included in the list.

If you choose a service registry, API Gateway sends a request to the service registry to discover the IP address and port at which the native service is running. API Gateway replaces the service registry alias in the Endpoint URI with the IP address and port returned by the service registry.

For example, if your service is hosted at the URL: http://host:port/abc/, you need to configure the Endpoint URI as: http://${ServiceRegistryName}/abc/.

As this property supports variable framework, you can make use of the available variables. For example, you can configure the endpoint URI using hard coded URL, simple alias, endpoint alias, and variable syntax or any of these combination. If you define the endpoint URI as http://${myAliasHost}:${request.headers.nativeport}/${sys:resource-path}, where the ${myAliasHost} variable syntax is used to define the simple alias and the ${request.headers.nativeport} variable syntax is used to define the native port based on the request.

For details about the variables available in webMethods API Gateway, see Variables Available in API Gateway.

Note: If you use endpoint alias, make sure the endpoint alias is created before you define it in the policy. For example, if you define ${alias} syntax in the policy before creating the alias as endpoint alias, webMethods API Gateway considers ${alias} as custom variable or simple alias and tries to resolve against those. So in that case, after creating endpoint alias you have to edit and save the API or policy to associate ${alias} syntax with the endpoint alias.
HTTP Method This is applicable to REST-based APIs.

Specifies the available routing methods: GET, POST, PUT, DELETE, and CUSTOM (default).

When CUSTOM is selected, the HTTP method in the incoming request is sent to the native service. When other methods are selected, the selected method is used in the request sent to the native service.

Note: IBM recommends to use Request Transformation > Method Transformation to achieve this as other transformations can also be done under the same policy.
SOAP Optimization Method This is applicable for SOAP-based APIs.

Specifies the optimization methods that webMethods API Gateway can use to parse SOAP requests to the native API.

Select one of the following options:

  • MTOM. webMethods API Gateway uses the Message Transmission Optimization Mechanism (MTOM) to parse SOAP requests to the API.
  • SwA. webMethods API Gateway uses the SOAP with Attachment (SwA) technique to parse SOAP requests to the API.
  • None. webMethods API Gateway does not use any optimization method to parse the SOAP requests to the API. This is selected by default.
HTTP Connection Timeout (seconds) Specifies the time interval (in seconds) after which a connection attempt times out.

The precedence of the Connection Timeout configuration is as follows:

  1. If you specify a value for the Connection timeout field in routing endpoint alias, then the Connection timeout value specified in the Endpoint alias section takes precedence over the timeout values defined at the API level and the global level.
  2. If you specify a value 0 for the Connection timeout field in routing endpoint alias, then webMethods API Gateway uses the value specified in the Connection timeout field in the routing protocol processing step of an API. The Read Timeout value specified at an API level takes precedence over the global configuration.
  3. If you specify a value 0 or do not specify a value for the Connection timeout field in the routing protocol processing step at the API level or specify a value 0 at an alias level, then webMethods API Gateway uses the value specified in this pg.endpoint.connectionTimeout property.
  4. If you do not specify any value for pg.endpoint.connectionTimeout, then webMethods API Gateway uses the default value of 30 seconds.
Read Timeout (seconds) Specifies the time interval (in seconds) after which a socket read attempt times out.

The precedence of the Read Timeout configuration is as follows:

  1. If you specify a value for the Read timeout field in routing endpoint alias, then the Read timeout value specified in the Endpoint alias section takes precedence over the timeout values defined at the API level and the global level.
  2. If you specify a value 0 for the Read timeout field in routing endpoint alias, then webMethods API Gateway uses the value specified in the Read Timeout field in the routing protocol processing step of an API. The Read Timeout value specified at an API level takes precedence over the global configuration.
  3. If you specify a value 0 or do not specify a value for the Read timeout field in the routing protocol processing step at the API level or specify a value 0 at an alias level, then webMethods API Gateway uses the value specified in this pg.endpoint.readTimeout property.
  4. If you do not specify any value for pg.endpoint.readTimeout, then webMethods API Gateway uses the default value of 30 seconds.
Pass WS-Security Headers This is applicable for SOAP-based APIs.

Selecting this indicates that webMethods API Gateway should pass the WS-Security headers of the incoming requests to the native API.

SSL Configuration. Configures keystore, key alias, and truststore for securing connections to native APIs.
Keystore Alias Specifies the keystore alias configured in webMethods API Gateway. This value (along with the value of Client Certificate Alias) is used for performing SSL client authentication.

Lists all available keystores. If you have not configured any keystore, the list is empty.

Key Alias Specifies the alias for the private key, which must be stored in the keystore specified by the keystore alias.
Truststore Alias Specifies the alias for the truststore that contains the list of CA certificates that API Gateway uses to validate the trust relationship with the native API.

If you do not configure any truststore alias, it implies that webMethods API Gateway does not validate the certificates provided by native APIs.

Service Registry Configuration
Service Discovery Endpoint Parameter Values required for constructing the discovery service URI.
  • Parameter: An alias that you have included in the discovery service URI while adding the service registry to API Gateway.
  • Value: Specifies a value with a syntax. The alias specified in Path Parameter is substituted with this value when invoking the discovery service.

For example: if the service registry configuration of the service registry that you have selected in Endpoint URI has Service discovery path set to /catalog/service/{serviceName} (and the {serviceName} alias is intended for passing the service name), you must enter {serviceName} as Parameter and the name of the service as Value.

As the Value field supports variable framework, you can make use of the available variables as path parameters.

For example, if you provide a parameter as {serviceName}( in Service discovery path while you define a service register) and the corresponding values for the path parameter as ${request.header.var1}, the value in var 1 retrieved from the request header will substitute the service name.

For details about the variables available in webMethods API Gateway, see Variables Available in API Gateway.

Rule. Defines the routing decisions based on one of the following routing options.
Route Using Defines the dynamic URL based on the HTTP header value sent by the client or the context variable value.

Select one of the following:

  • Header: Select and specify the Name required. This header name is configured by the API provider and is used to decide the routing decisions at the API level. The request message must be routed to the dynamic URL generated from the HTTP header value.
  • Context: The API providers must provide IS service in the policy, Invoke webMethods Integration Server. IS service would perform custom manipulations and set the value for the Context Variable ROUTING_ENDPOINT. webMethods API Gateway takes this ROUTING_ENDPOINT value as the native endpoint value and performs the routing.
  • Name. This field is displayed only when you select Header as the routing method. Type a name for the Routing header. API Gateway expects this header name in the incoming request that invokes the API.
Route To Specifies the endpoint URI of native services in a pool to which the requests are routed.
Provide the following information:
  • Endpoint URI . Specifies the URI of the native API endpoint to route the request to. You can use service registries in a similar manner as described in the main Endpoint URI above.

    As this property supports variable framework, you can make use of the available variables. For example, you can configure the endpoint URI using hard coded URL, simple alias, endpoint alias, and variable syntax or any of these combination. If you define the endpoint URI as http://${myAliasHost}:${request.headers.nativeport}/${sys:resource-path}, where the ${myAliasHost} variable syntax is used to define the simple alias and the ${request.headers.nativeport} variable syntax is used to define the native port based on the request.

    You can also use the system-defined alias ${sys:dyn-Endpoint}. When you use the system-defined alias, the variables are replaced at runtime by the Header value or the Context value, selected as the Route To option.

    Consider the following URL with the system-defined alias:


    http://HOSTNAME:5555/rest/com/
    softwareag/mediator/samples/dynamicRouting/
    validateDynamicURI/${sys:dyn-Endpoint}

    Now, if the incoming request has Header value as resource, the ${sys:dyn-Endpoint} alias in the URL is replaced by the Header value and the effective URL is


    http://HOSTNAME:5555/rest/com/
    softwareag/mediator/samples/dynamicRouting/validateDynamicURI/
    resource    .

    For details about the variables available in webMethods API Gateway, see Variables Available in API Gateway.

    Note: If you use endpoint alias, make sure the endpoint alias is created before you define it in the policy. For example, if you define ${alias} syntax in the policy before creating the alias as endpoint alias, webMethods API Gateway considers ${alias} as custom variable or simple alias and tries to resolve against those. So in that case, after creating endpoint alias you have to edit and save the API or policy to associate ${alias} syntax with the endpoint alias.
  • HTTP Method. This applicable to REST-based APIs. Specifies the available routing methods: GET, POST, PUT, DELETE, and CUSTOM (default).

    When CUSTOM is selected, the HTTP method in the incoming request is sent to the native service. When other methods are selected, the selected method is used in the request sent to the native service.

  • HTTP Connection Timeout (seconds). Specifies the time interval (in seconds) after which a connection attempt times out.

    The precedence of the Connection Timeout configuration is as follows:

    1. If you specify a value for the Connection timeout field in routing endpoint alias, then the Connection timeout value specified in the Endpoint alias section takes precedence over the timeout values defined at the API level and the global level.
    2. If you specify a value 0 for the Connection timeout field in routing endpoint alias, then webMethods API Gateway uses the value specified in the Connection timeout field in the routing protocol processing step of an API. The Read Timeout value specified at an API level takes precedence over the global configuration.
    3. If you specify a value 0 or do not specify a value for the Connection timeout field in the routing protocol processing step at the API level or specify a value 0 at an alias level, then webMethods API Gateway uses the value specified in this pg.endpoint.connectionTimeout property.
    4. If you do not specify any value for pg.endpoint.connectionTimeout, then webMethods API Gateway uses the default value of 30 seconds.
  • Read Timeout (seconds). Specifies the time interval (in seconds) after which a socket read attempt times out.

    The precedence of the Read Timeout configuration is as follows:

    1. If you specify a value for the Read timeout field in routing endpoint alias, then the Read timeout value specified in the Endpoint alias section takes precedence over the timeout values defined at the API level and the global level.
    2. If you specify a value 0 for the Read timeout field in routing endpoint alias, then webMethods API Gateway uses the value specified in the Read Timeout field in the routing protocol processing step of an API. The Read Timeout value specified at an API level takes precedence over the global configuration.
    3. If you specify a value 0 or do not specify a value for the Read timeout field in the routing protocol processing step at the API level or specify a value 0 at an alias level, then webMethods API Gateway uses the value specified in this pg.endpoint.readTimeout property.
    4. If you do not specify any value for pg.endpoint.readTimeout, then webMethods API Gateway uses the default value of 30 seconds.
  • SSL Configuration. Configures keystore, key alias, and truststore for securing connections to native APIs. Provide the following information:
    • Keystore Alias. Specifies the keystore alias configured in webMethods API Gateway. This value (along with the value of Client Certificate Alias) is used for performing SSL client authentication.

      Lists all available keystores. If you have not configured any keystore, the list is empty.

    • Key Alias. Specifies the alias for the private key, which must be stored in the keystore specified by the keystore alias.
    • Truststore Alias. Specifies the alias for the truststore that contains the list of CA certificates that API Gateway uses to validate the trust relationship with the native API.

      If you do not configure any truststore alias, it implies that webMethods API Gateway does not validate the certificates provided by native APIs.

SOAP Optimization Method This is applicable for SOAP-based APIs.

Specifies the optimization methods that webMethods API Gateway can use to parse SOAP requests to the native API.

Select one of the following options:

  • MTOM. webMethods API Gateway uses the Message Transmission Optimization Mechanism (MTOM) to parse SOAP requests to the API.
  • SwA. webMethods API Gateway uses the SOAP with Attachment (SwA) technique to parse SOAP requests to the API.
  • None. webMethods API Gateway does not use any optimization method to parse the SOAP requests to the API. This is selected by default.
Pass WS-Security Headers This is applicable for SOAP-based APIs.

Selecting this indicates that webMethods API Gateway should pass the WS-Security headers of the incoming requests to the native API.