Policies

API Gateway provides a policy framework to manage and secure APIs.

A policy can be enforced on an API to perform specific tasks, such as transport, security, logging, routing of requests to target services, and transformation of data from one format to another. You can also define a policy to evaluate and process the various API invocations at run-time. For example, a policy could instruct API Gateway to perform any of the following tasks and prevent malicious attacks:

  • Verify that the requests submitted to an API come from applications that are authenticated and authorized using the specified set of identifiers in the HTTP header to access and use the particular API.

  • Validate digital signatures in the security header of request and response messages.

  • Monitor a user-specified set of run-time performance conditions and limit the number of invocations during a specified time interval for a particular API and for applications, and send alerts to a specified destination when these performance conditions are violated.

  • Log the request and response messages, and the run-time performance measurements for APIs and applications.

Overview

Policies are grouped into stages as per their usage. For example, the policies in a Threat Protection stage can be enforced for all APIs to protect against malicious attacks that could cause problems such as, large and recursive payloads, viruses, scanning with external systems, and SQL injections. The policies in the Identify and Access stage can be enforced on an API to specify the kind of identifiers that are used to identify the application and authorize it against all applications registered in API Gateway.

Policy enforcement mode

You can enforce policies in an API in the following ways:

After you apply the policies both globally (through global policies) and directly (through API-level policies and scope-level policies) to an API, API Gateway determines the effective set of policies for that API by taking into account the precedence of policy enforcement at the API-level, the policy stages, the priority of policies, run-time constraints, and the status (activated or deactivated) of any applied global policy.

Policy hierarchy

You can enforce policies on an API at the following levels:

For example, if an API was given the Identify and Authorize Application policy at the following policy enforcement levels:

  1. Global Policy Enforcement

  2. API-level Policy Enforcement

  3. Resource-level Policy Enforcement

  4. Method-level Policy Enforcement (or) Operation-level Policy Enforcement

The precedence of the policy enforcement which are effective for the API at run-time is as follows:

  1. Global Policy Enforcement

  2. Method-level Policy Enforcement (or) Operation-level Policy Enforcement

  3. Resource-level Policy Enforcement

  4. API-level Policy Enforcement

If the API has the Identify and Authorize Application policy applied through both a global policy and at the API-level, API Gateway does not show conflict. The Identify and Authorize Application policy applied through the global policy takes precedence and is processed at run-time.

Similarly for a REST API, Identify and Authorize Application policy is applied through a scope-level policy (at the resource-level) and also at the API-level, the Identify and Authorize Application policy applied through the scope-level policy takes precedence and is processed at run-time.

Transaction logging policy

API Gateway provides a system global policy, Transaction logging, which is shipped with the product. By default, the policy is in the Inactive state. The transaction logging policy has standard filters and log invocation policy that log request or response payloads to a specified destination. You can edit this policy to include additional filters or modify the policy properties but you cannot delete this policy. You can activate this policy in the Polices > Global policies page or through the Global Policy details page. Activating the policy enforces it on all APIs in API Gateway based on the configured filters and logs transactions across all the APIs. If you have multiple log invocation policies assigned to an API, the policies are compiled into a single policy and the one transaction log is created per destination.

Policy Validation and Dependencies

When you enforce a policy to govern an API at run-time, API Gateway validates the policies to ensure that:

When you save an API, API Gateway combines the policies from all of the global and direct policies that apply to the API (that is, at the API-level) and generates what is called the effective policy for the API. For example, let’s say your REST API is within the scope of two policies: one policy that performs a logging task and another policy that performs a security task. When you save the REST API, API Gateway automatically combines the two policies into one effective policy. The effective policy, which contains both the logging task and the security task, is the policy that API Gateway actually uses to publish the REST API.

When API Gateway generates the effective policy, it validates the resulting policy to ensure that it contains no conflicting or incompatible policies.

If the policy contains conflicts or inconsistencies, API Gateway computes the effective API policy according to policy resolution rules. For example, an effective API policy can include only one Identify and Authorize Application policy. If the resulting policy list contains multiple Identify and Authorize Application policies, API Gateway shows the conflict by including an including a Conflict (icon) icon next to the name of the conflicting policies in the effective policy.

The following table shows:

Policy Validation and Dependencies:

Policy Applicable API Type Dependent Policy Mutually Exclusive Policy Can include multiple times in an API?
Conditional Error Processing REST SOAP None. None. Yes. API Gateway includes all Conditional Error Processing policies in the effective policy.
Content-based Routing REST SOAP None. Straight Through Routing, Load Balancer Routing, Dynamic Routing, Context-based Routing No. API Gateway includes only one policy in the effective policy.
Context-based Routing REST SOAP None. Straight Through Routing, Load Balancer Routing, Dynamic Routing, Content-based Routing No. API Gateway includes only one policy in the effective policy.
Custom HTTP Header REST SOAP None. None. No. API Gateway includes only one policy in the effective policy.
Data Masking (Error Handling) REST SOAP None. None. No. API Gateway includes only one policy in the effective policy.
Data Masking (Response Processing) REST SOAP None. None. No. API Gateway includes only one policy in the effective policy.
Data Masking (Request Processing) REST SOAP None. None. No. API Gateway includes only one policy in the effective policy.
Dynamic Routing REST SOAP None. Straight Through Routing, Load Balancer Routing, Content-based Routing, Context-based Routing No. API Gateway includes only one policy in the effective policy.
Enable HTTP / HTTPS REST SOAP None. None. No. API Gateway includes only one policy in the effective policy.
Identify and Authorize Application REST SOAP Inbound Authentication - Message policy is required if Identification Type is configured as WS Security Username Token or WS Security X.509 Certificate or Kerberos Token for SOAP-based APIs. None. No. API Gateway includes only one policy in the effective policy.
Inbound Authentication - Message SOAP None. None. No. API Gateway includes only one policy in the effective policy.
Invoke webMethods IS (Response Processing) REST SOAP None. None. Yes. API Gateway includes all Invoke webMethods IS policies in the effective policy.
Invoke webMethods IS (Request Processing) REST SOAP None. None. Yes. API Gateway includes all Invoke webMethods IS policies in the effective policy.
Load Balancer Routing REST SOAP None. Straight Through Routing, Dynamic Routing, Content-based Routing, Context-based Routing No. API Gateway includes only one policy in the effective policy.
Log Invocation REST SOAP None. None. Yes. API Gateway includes all Log Invocation policies in the effective policy.
Monitor Performance REST SOAP None. None. Yes. API Gateway includes all Monitor Performance policies in the effective policy.
Monitor SLA REST SOAP Identify and Authorize Application None. Yes. API Gateway includes all Monitor SLA policies in the effective policy.
Outbound Authentication - Message SOAP None. None. No. API Gateway includes only one policy in the effective policy.
Outbound Authentication - Transport REST SOAP None. None. No. API Gateway includes only one policy in the effective policy.
Response Transformation REST SOAP None. None. Yes. API Gateway includes all XSLT Transformation policies in the effective policy.
Request Transformation REST SOAP None. None. Yes. API Gateway includes all XSLT Transformation policies in the effective policy.
Service Result Cache REST SOAP None. None. No. API Gateway includes only one policy in the effective policy.
Set Media Type REST None. None. No. API Gateway includes only one policy in the effective policy.
Straight Through Routing REST SOAP None. Load Balancer Routing, Dynamic Routing, Content-based Routing, Context-based Routing No. API Gateway includes only one policy in the effective policy.
Traffic Optimization REST SOAP Identify and Authorize Application None. Yes. API Gateway includes all Traffic Optimization policies in the effective policy.
Validate API Specification (Response Processing) REST SOAP None. None. No. API Gateway includes only one policy in the effective policy.
Validate API Specification (Request Processing) REST SOAP None. None. No. API Gateway includes only one policy in the effective policy.

Managing Threat Protection Policies

Threat protection policies prevent malicious attacks from client applications that typically involve large, recursive payloads, and SQL injections. You can limit the size of things, such as maximum message size, maximum number of requests, and maximum node depth and text node length, in the XML document. You can configure the global threat protection policies and rules for all the incoming requests that comes through the external port of API Gateway. These policies and rules are enforced by API Gateway based on your configuration.

You must have the API Gateway’s manage threat protection functional privilege to configure the following policies and rules.

In addition, the API Gateway administrator can configure the necessary mobile devices and applications for which you want to deny the access, configure and customize the deny and alert rules, and manage the denied IPs.

Basically, when you configure the threat protection policy in a clustered setup, you specify the limitations (such as number of requests and concurrent request) that an API Gateway instance in the cluster can handle during a specified time interval. Hence, if you add X number of API Gateway instances, the limitations set in the configuration also increases by X times.

For example, if you have two API Gateway instances and set the limitations as 100 requests per minute, then the API Gateway instances should be able to handle 200 requests per minute. When you add one more API Gateway instance, the processing capacity also increases to 300 requests per minute. Here, the API Gateway cluster used for Threat Protection does not act as a single unit.

Note: When you have configured a load balancer, the load balancer exposes the actual client IP address using the X-Forwarded-For (XFF) headers. The watt.server.enterprisegateway.ignoreXForwardedForHeaderproperty specifies whether API Gateway uses or ignores the IP address in the XFF headers. By default, API Gateway ignores the client IP address and so the watt.server.enterprisegateway.ignoreXForwardedForHeader property is set to true. If you want API Gateway to use the actual client IP address present in the XFF, then set the watt.server.enterprisegateway.ignoreXForwardedForHeader property to false.

Configuring Global Denial of Service Policy

You can configure this policy in API Gateway to prevent Denial of Service (DoS) attacks. One form of DoS attack occurs when a client floods a server with many requests in an attempt to interfere with server processing. Using API Gateway, you can limit the number of requests that API Gateway accepts within a specified time interval and the number of requests that it can process concurrently. By specifying these limits, you can protect API Gateway from DoS attacks.

You can configure API Gateway to limit the total number of incoming requests from the external ports. For example, you might want to limit the total number of requests received to 1000 requests in 10 seconds, and limit the number of concurrent requests to 100 requests in 10 seconds. When API Gateway detects that a limit has been exceeded, it blocks the exceeding requests for a specific time interval and displays an error message to the client based on your configuration. You can also configure a list of trusted IP addresses so that the requests from these IP addresses are always allowed and not blocked.

To configure global denial of service policy

To configure global denial of service policy

  1. Click Policies in the title navigation bar.

  2. Select Threat protection > Global denial of service.

  3. Set the Enable button to the On position to enable the policy.

  4. Type the maximum number of requests, in the Maximum requests field, that API Gateway can accept from any IP address in a given time interval.

  5. Specify time in seconds, in the In (seconds) field, in which the maximum requests have to be processed.

  6. Type the maximum number of concurrent requests, in the Maximum requests in progress field, that API Gateway can process concurrently.

  7. Specify the time in minutes, in the Block intervals (minutes) field, for which you want requests to be blocked.

  8. Type the alert message text, in the Error message field, to be displayed when the policy is breached.

  9. Add IP addresses, in the Trusted IP addresses field, that can be trusted and are always allowed.

    • API Gateway supports IPv4 and IPv6 addresses in the trusted IP addresses lists.

    • You can specify a range of IP addresses using the classless inter-domain routing (CIDR) notation. To specify an IP address range, type the first IP address in the range followed by a forward slash (/) and a CIDR suffix.

      Example IPv4 address range:

      • 192.168.100.0/22 represents the IPv4 addresses from 192.168.100.0 to 192.168.103.255
      • 148.20.57.0/30 represents the IPv4 addresses from 148.20.57.0 to 148.20.57.3

      Example IPv6 address range:

      • f000::/1 represents the IPv6 addresses from f000:: to ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff.
      • 2001:db8::/48 represents the IPv6 addresses from 2001:db8:0:0:0:0:0:0 to 2001:db8:0:ffff:ffff:ffff:ffff:ffff.

    Click icon to add more than one IP address.

  10. Click Save.

Configuring Denial of Service by IP Policy

You can configure this policy in API Gateway to prevent Denial of Service (DoS) attacks. One form of DoS attack occurs when a particular client floods a server with many requests in an attempt to interfere with server processing and not letting other clients in accessing the server. Using Denial of Service (DoS) by IP policy, you can limit the number of requests that API Gateway accepts from a particular IP address within a specified time interval and the number of requests that it can process concurrently from any IP address. By specifying these limits, you can protect API Gateway from DoS attacks by a particular IP address. When API Gateway detects that a limit has been exceeded, it blocks or denies the requests from that particular IP address and displays an error message to the client based on your configuration. You can also configure a list of trusted IP addresses so that the requests from these IP addresses are always allowed and not denied.

Note: To configure the denial of service by IP policy, you have to set watt.server.enterprisegateway.ignoreXForwardedForHeader property to false. When this setting is configured, the incoming request header will have the XFF header and tracks actual client IP address, which in turn allows you to configure DoS by IP.

To configure the denial of service by IP policy

  1. Click Policies in the title navigation bar.

  2. Select Threat protection > Denial of service by IP.

  3. Set the Enable button to the On position to enable the policy.

  4. Type the maximum number of requests, in the Maximum requests field, that API Gateway can accept from a specific IP address in a given time interval.

  5. Specify time in seconds, in the In (seconds) field, in which the maximum requests have to be processed.

  6. Type the maximum number of requests, in the Maximum requests in progress field, that API Gateway can process concurrently from any single IP address.

  7. Select one of the following actions to be taken when the number of requests from a non-trusted IP address exceeds the specified limits:

    • Add to deny list to permanently deny future requests from the IP address.

    • Block temporarily block requests from this IP address.

  8. Type the alert message text, in the Error message field, to be displayed when the policy is breached.

  9. Add IP addresses, in the Trusted IP Addresses field, that can be trusted and not blocked.

    • API Gateway supports IPv4 and IPv6 addresses in the trusted IP addresses lists.

    • You can specify a range of IP addresses using the classless inter-domain routing (CIDR) notation. To specify an IP address range, type the first IP address in the range followed by a forward slash (/) and a CIDR suffix.

      Example IPv4 address range:

      • 192.168.100.0/22 represents the IPv4 addresses from 192.168.100.0 to 192.168.103.255
      • 148.20.57.0/30 represents the IPv4 addresses from 148.20.57.0 to 148.20.57.3

      Example IPv6 address range:

      • f000::/1 represents the IPv6 addresses from f000:: to ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff.
      • 2001:db8::/48 represents the IPv6 addresses from 2001:db8:0:0:0:0:0:0 to 2001:db8:0:ffff:ffff:ffff:ffff:ffff.

    Click icon to add more than one IP address.

  10. Click Save.

Managing Denied IP List

The Denied IPs section has a list of client IPs that were denied access due to breach of denial of service by IP policy. You can delete the IP from the denial list and make it available on client’s request.

To manage the denied IP list

  1. Click Policies in the title navigation bar.

  2. Select Threat protection > Denied IPs.
    This displays a list of IP address that are denied from access.

  3. Click icon in the Action column so that the specified IP can be made available.

Configuring Rules

You can configure rules to filter malicious requests based on message size, authentication requests, requests from specific mobile devices and applications that could be harmful, requests that could cause an SQL injection attack, requests on anti-virus scan, XML / JSON requests, or use custom filters to avoid malicious attacks.

API Gateway applies rules in the order in which they are displayed on the Threat Protection > Rules screen. Because a violation of a denial rule stops API Gateway from processing a request, hence it is important to prioritize the rules based on the order in, which you want them to be executed. The API Gateway processes denial rules followed by the alert rules.

To configure rules

  1. Click Policies in the title navigation bar.

  2. Select Threat protection > Rules.
    This displays a list of rules that are already configured.

  3. Click Add rule.

  4. In the Rule properties section provide the following information:

    a. Type a name for the rule in the Rule name field. Valid rule names:

    • Must be unique.

    • Must not be empty.

    • Must not contain spaces.

    • Must not contain the special characters - ? ~ ` ! @ # $ % ^ & * ( ) - + = { } | [ ] \\ : \” ; ‘ < > , /

    b. Type a description for the rule in the Description field.

    c. Select an action to be followed when the policy is violated:

    • Deny request and alert to deny the access and send an alert when the policy is violated.

    • Alert to allow the request and send an alert when the policy is violated.

    d. Type the alert message text, in the Error message field, to be displayed when the policy is violated.

    e. Select the required Request type to which you want to apply the rule and provide the additional information required.

    The available values are:

    • ALL: Applies the rule to all requests.

    • REST: Applies the rule to all REST requests.

    • SOAP: Applies the rule to all SOAP requests

    • INVOKE: Applies the rule to all INVOKE requests.

    • CUSTOM: Applies the rule to all requests specified by the custom directives. You can use this option if you want a single rule applied for multiple request types and custom directives.

    f. Provide the following information to filter the requests depending on the Request type selected:

    • Resource path: Provide the Resource path for the REST, SOAP, INVOKE, or CUSTOM Request type selected to filter the requests based on the resource being requested. The format for the REST, SOAP, and INVOKE request types is folder_name/service_name and the format for a CUSTOM request type is given_directive/service_name. You can add multiple resource paths using the Add button.

    • Custom directives: Provide the custom directives for the CUSTOM Request type to filter the incoming requests. For example, if you provide gateway as the directive, the rule applies to all these requests that are received in API Gateway with the directive gateway. You can add multiple directives using the Add button.

  5. Configure the required filters as follows:

    • Alert settings. Select one of the following options:

      • Default: Sets the default alert settings to be used.

      • Custom: You can specify this option to use the custom alert settings and provide the required information.

        • Alert destination: Specify the alert destination. Values are Email and Flow service. If you select Email, provide the email ids to which the alert notification has to be sent. If you select Flow service, a flow service is invoked. Specify the name of the flow service. You can create a flow service using the pub.security.enterpriseGateway:alertSpec as the signature of the service and or use the pre-defined flow service, pub.apigateway.threatProtection:violationListener. When you use the pre-defined service, the alerts are saved in API Gateway Data Store and displayed in API Gateway Dashboard. For more information on the pub.security.enterpriseGateway:alertSpec specification, refer to the Integration Server Build-In Services Reference Guide.

        • Provide the user, who has permissions to execute the service, as the user type. For example, Administrator

      Send alert: Select a condition depending on when you want the alert to be sent. Available values are On rule violation which sends an alert every time a request violates a rule or Every and specify the time interval (in minutes), which send alerts at specified intervals.

    • Message size filter

      • Set the Enable button to the On position to enable the filter.

      • Type the maximum size allowed for HTTP and HTTPS requests in the Maximum message size (MB) field.
        If the request is larger than the size specified in this limit, the request violates the rule and API Gateway performs the configured action.

    • OAuth filter

      • Set the Enable button to the On position to enable the filter.

      • Set the Require OAuth credentials toggle button to the On position. This implies the request should contain the OAuth credentials else the request would be denied.

    • Mobile application protection filter

      You can configure this filter to disable access for certain mobile application versions on a predefined set of mobile platforms. By disabling access to these versions, you are ensuring that all users are using the latest versions of the applications and taking advantage of the latest security and functional updates.

      • Set the Enable button to the On position to enable the filter.

      • Select the device type.

      • Select the mobile application.

      • Select the operator condition =, >, <, >=, <= or <>.

      • Type the mobile application version.

      You can add multiple entries by clicking icon.

    • SQL injection protection filter

      You can use the SQL injection protection filter to block requests that could possibly cause an SQL injection attack. When this filter is enabled, API Gateway checks each request message for specific patterns of characters or keywords that are associated with potential SQL injection attacks. If a match is found in the request parameters or payload, API Gateway blocks the request from further processing.

      • Set the Enable button to the On position to enable the selected filter.

      • Select the required filters as follows:

        • Select Database-specific SQL injection protection and select a database against which specific parameters needs to be checked.

          When enabled, API Gateway checks the incoming payload based on the specified database and GET or POST request parameters. If no parameter is specified, all input parameters are checked for possible SQL injection attack.

        • Select Standard SQL injection protection and specify one or more GET or POST request parameters that could be present in the incoming requests. Parameters can contain only alphanumeric characters, dollar sign ($), and underscore (_).

          You can add multiple entries by clicking icon.

    • Anti virus scan filter

    • You can use the antivirus scan filter to configure API Gateway to interact with an Internet Content Adaptation Protocol (ICAP)-compliant server. An ICAP server is capable of hosting multiple services that you can use to implement features such as virus scanning or content filtering. Using the antivirus scan filter, API Gateway can leverage the ICAP protocol to scan all incoming HTTP requests and payloads for viruses.

      • Set the Enable button to the On position to enable the filter.

      • Type the antivirus ICAP engine name in the ICAP name field.

      • Type the host name or IP address of the machine on which the ICAP server is running in the ICAP host name or IP address field.

      • Type the port number on which the ICAP server is listening in the ICAP port number field.

      • Type the name of the service exposed by the ICAP server that you can use to scan your payload for viruses in the ICAP service name field.

    • JSON threat protection filter

      You can use this filter to block attacks through JSON payload that have infinitely long strings or deeply nested payloads. Software AG recommends that this protection should be combined with message size filter to identify infinite payloads.

      Set the Enable button to the On position to enable the filter.

      You can specify any of these parameters as filter criteria. If you do not specify a value, the system applies a default value of -1, which means an unlimited value.

      Field Description
      Container depth Specifies the maximum allowed containment depth, where the containers are objects or arrays.
      For example, an array containing an object which contains an object would result in a containment depth of 3.
      Object entry count Specifies the maximum number of entries allowed in an object.
      Object entry name length field Specifies the maximum string length allowed for a property name within an object.
      Array element count Specifies the maximum number of elements allowed in an array.
      String value length Specifies the maximum length allowed for a string value.
      Applicable content type Specify any other content types to be included in the filter.
      You can add more entries by clicking icon.
    • XML threat protection filter

      You can use this filter to block attacks through XML payload that have infinitely long strings or deeply nested payloads. Software AG recommends that this protection should be combined with message size filter to identify infinite payloads.

      Set the Enable button to the On position to enable the filter.

      You can specify any of these parameters as filter criteria. If you do not specify a value, the system applies a default value of -1, which the system equates to no limit.

      Field Description
      Namespace prefix length Specifies a limit on the maximum number of characters permitted in the namespace prefix in the XML document.
      Namespace URI length Specifies a character limit for any namespace URIs present in the XML document.
      Namespace count per element Specifies the maximum number of namespace definition allowed for any element.
      Child count Specifies the maximum number of child elements allowed for any element.
      Attribute name length Specifies a limit on the maximum number of characters permitted in any attribute name in the XML document.
      Attribute value length Specifies a limit on the maximum number of characters permitted in any attribute value in the XML document.
      Attribute count per element Specifies the maximum number of attributes allowed for any element.
      Element name length Specifies a limit on the maximum number of characters permitted in any element name in the XML document.
      Text length Specifies a character limit for any text node present in the XML document.
      Comment length Specifies a character limit for any comments present in the XML document.
      Processing instruction target length Specifies a limit on the maximum number of characters permitted in the target of any processing instructions in the XML document.
      Processing instruction data length Specifies a limit on the maximum number of characters permitted in the data value of any processing instructions in the XML document.
      Node depth Specifies the maximum node depth allowed in the XML.
      Applicable content types Specify any other content types to be included in the filter.
      You can add multiple values by clicking icon.
  6. Click Save.
    The new rule is created and appears in the list of rules in the Rules page.

The rule is applied to requests only if the rule is enabled. You can enable the rule in the Rules page by selecting the enable icon for the required rule.

Registering a Mobile Device or Application

You can use API Gateway to disable access for certain mobile application versions on a predefined set of mobile platforms. By registering the required devices and applications and disabling access to these versions, you ensure that all users use the latest versions of the applications and take advantage of the latest security and functional updates.

To register a mobile device or application

  1. Click Policies in the title navigation bar.

  2. Select Global Policies > Mobile devices and apps.

  3. Provide the mobile device type name and click icon.
    You can add more entries by clicking icon. You can delete the added ones by clicking icon.

  4. Provide the mobile application name and click icon.
    You can add more entries by clicking icon. You can delete the added ones by clicking icon.

  5. Click Save.

Configuring Alert Settings

You can configure the alert settings to control the following aspects of alerts that API Gateway sends when a request violates a rule:

To configure alert settings

  1. Click Policies in the title navigation bar.

  2. Select Global Policies > Alert settings.

  3. Select one or both the alert destination types:

    • Email. This sends email alerts.

      • Type the email ids to which the email has to be sent.

    • Flow Service. This invokes a flow service to alert you of a rule violation. Specify the name of the flow service. You can create a flow service using the pub.security.enterpriseGateway:alertSpec specification as the signature of the service or use the pre-defined flow service, pub.apigateway.threatProtection:violationListener. When you use the predefined service, the alerts are saved in API Gateway Data Store and displayed API Gateway Dashboard. For more information on the pub.security.enterpriseGateway:alertSpec specification, refer to the Integration Server Build-In Services Reference Guide.

      • Provide the user, who has permissions to execute the service, as the user type. For example, Administrator.

  4. Select one of the following conditions depending on when you want the alert to be sent.

    • On rule violation to send an alert every time a request violates a rule.

    • Every and specify the time interval (in minutes) to send to send alerts at specified intervals.

  5. Click Save.

System-defined Stages and Policies

API Gateway provides system-defined policies that are grouped into stages depending on their usage.

In each stage of the system-defined policies, you define multiple policy parameters to configure the values. By default, all the policy parameters use hardcoded value to configure the values. For some of the policy parameters, you can configure the value using variable syntax. During run-time, the value gets extracted based on the request or response.

Variable Framework

All types of variables such as request, response, custom, custom-context, and system context variables are handled through the common framework called variable framework. The variable framework in API Gateway provides an option to extract variable values that can be used across stages. For example, you can use the extracted variable to transform request and response contents such as headers, query parameters, path parameters payload, and so on as per your requirement. With the variable framework, you can normalize the syntax and create a common template for accessing the various variable types.

The following table summarizes the keywords that are used to define the variable syntaxes:

Variable keyword Description
paramStage Defines the stage of the system defined policy. Possible values are:
  • request
  • response
paramType Defines the specific parameter of the request or response. Possible values are:
  • payload
  • headers
  • query
  • path
  • httpMethod
  • statusCode
  • statusMessage
queryType Defines the query that can be applied over string elements like payload. Possible values are:
  • xpath
  • jsonPath
  • regex

The following variable types are available in the request or response stages:

You can use this syntax to access the following string variables: path, statusCode, statusMessage, httpMethod.

Examples: ${request.path}, ${response.statusCode}

You can use this syntax to access map types, such as query, headers, and path.

Example: ${request.query.var1}, ${response.header.Content-Type}, ${request.path.name}.

You can use this syntax to access the payload. Examples:

Note: While xpath and jsonPath are applicable only to payload, regEx can be used with both payload and path.

You can use this syntax to access the header or payload in the request or response stage.

Example:

Variable: ${response.headers.id}

Value: ${response[customExtension].payload.jsonPath[$.id]}

This transformation adds a header to the response with the name id, and its value is derived from the JSON payload that is sent from the external callout as per the JSON path.

The following sections summarize the variables that are available in API Gateway as part of variable framework template in addition to the existing predefined system context and custom context variables:

Request Variables

Variables that allow you to extract and reuse values in the request processing stage.

Variable Syntax Description
${request.headers.NAME}
Example: ${request.headers.Content-Type}
Gets the value of the header name in the request.
${request.query.NAME}
Example: ${request.query.var1}
Gets the value of the query name in the request.
${request.path} Gets the value of the path in the request.
${request.path.regex[EXPR]}
Example: ${request.path.regex[0]}
Gets the value of the path in the request.
${request.httpMethod} Gets the method in the request.
${request.payload.xpath[EXPR]}
Example:${request.payload.xpath[//ns:emp/ns:empName]}, where //ns:emp/ns:empName is the xpath to be applied on the payload if contentType is application/xml
Gets the value after applying a xpath expression on the request path.
Note: The namespace URI for the prefixes you have configured in the xpath expression are resolved using namespaces configured in the metadata section in the policy or using the namespaces configured through XpathNamespaces custom variable in the custom extension policy.
${request.payload.jsonPath[EXPR]}
Example: ${request.payload.jsonPath[$.cardDetails.number]} where $.cardDetails.number is the jsonPath to be applied on the payload if contentType is application/json
Gets the value after applying a json expression on the request path.
${request.payload.regex[EXPR]}
Example: ${request.payload.regex[[0-9]+]} where [0-9]+ is the regex to be applied on the payload if contentType is text/plain
Gets the value after applying a regular expression on the request path.
${request.authorization.clientId} Gets the value of the client ID identified from the authorization header by the configured IAM policy. This value is available only if the relevant IAM policy is configured.
${request.authorization.issuer} Gets the value of the issuer identified from the authorization header by the configured IAM policy. This value is available only if the relevant IAM policy is configured.
${request.authorization.userName} Gets the value of the username identified from the authorization header by the configured IAM policy. This value is available only if the relevant IAM policy is configured.
${request.authorization.authHeader} Gets the value of the authorization header by the configured IAM policy. This value is available only if the relevant IAM policy is configured.
${request.authorization.apiKey} Gets the value of the API key from the authorization header by the configured IAM policy. This value is available only if the relevant IAM policy is configured.
${request.authorization.incomingToken} Gets the value of the incoming token from the authorization header by the configured IAM policy. This value is available only if the relevant IAM policy is configured.
${request.authorization.audience} Gets the value of the audience from the authorization header by the configured IAM policy. This value is available only if the relevant IAM policy is configured.
${request.authorization.claims.CLAIM_NAME}
Example: ${request.authorization.claims.emp.company}
Gets the value for the claim name from the claims identified from the Authorization header by the configured IAM policy. This value is available only if the relevant IAM policy is configured
${request.correlationID} Gets the correlation ID for this request.
${request.application.id} Gets the ID of the application identified for this request.
${request.application.name} Gets the name of the application identified for this request.
${request.application.version} Gets the version ID of the application identified for this request.
${request.application.claims.CLAIM_NAME}
Example:${ request.application.claims.sample }
Gets the value of the claim name for the claims identifier configured in the application identified for this request.
${request.application.partnerId} Gets the partner ID of the application identified for this request.
${request.application.description} Gets the description of the application identified for this request.
${request.application.hostname[NUMBER]}
Example: ${ request.application.hostname[0]}
Gets the value of the hostname identifier in the specified index for the application identified for this request.
${request.application.payloadIdentifier[NUMBER]}<br> Example:${request.application.payloadIdentifier[1]}` Gets the value of the payload identifier in the specified index for the application identified for this request.
${request.application.team[NUMBER]}
Example: ${request.application.team[0]}
Gets the value of the team identifier in the specified index for the application identified for this request.
${request.application.token[NUMBER]}
Example:${request.application.token[1]}
Gets the value of the token identifier in the specified index for the application identified for this request.
${request.application.username[NUMBER]}
Example:${request.application.username[0]}
Gets the value of the username identifier in the specified index for the application identified for this request.
${request.application.wssUsername[NUMBER]}
Example:${request.application.wssUsername[0]}
Gets the value of the wssUsername identifier in the specified index for the application identified for this request.
${request.application.headers.HEADER_NAME}
Example:${request.application.headers.Accept}
Gets the value of the header name for the headers identifier configured in the application identified for this request.

Response variables

Variables that allow you to extract and reuse values in the response processing stage.

Variable Syntax Description
${response.headers.NAME}
Example: ${response.headers.Accept}
Gets the value of the header name in the response.
${response.statusCode} Gets the value for the status code for the response.
${response.statusMessage} Gets the value for the status message in the response
${response.payload.xpath[EXPR]}
Example:${response.payload.xpath[//ns:emp/ns:empName]} where //ns:emp/ns:empName is the xpath to be applied on the payload if contentType is application/xml
Gets the value of the payload from the specified xpath of the response.
Note: The namespace URI for the prefixes you have configured in the xpath expression are resolved using namespaces configured in the metadata section in the policy or using the namespaces configured through XpathNamespaces custom variable in the custom extension policy.
${response.payload.jsonPath[EXPR]}
Example:${response.payload.jsonPath[$.cardDetails.number]} where $.cardDetails.number is the jsonPath to be applied on the payload if contentType is application/json
Gets the value of the payload from the specified jsonPath of the response.
${response.payload.regex[EXPR]}
Example: ${ response.payload.regex[[0-9]+]} where [0-9]+ is the regex to be applied on the payload if contentType is text/plain
Gets the value of the payload from the specified regex of the response.

API Gateway evaluates and supports the array expressions in JSON path.

Example: Consider the following payload.



{
"firstName":"John",
"lastName":"doe",
"age":26,
"address":
{"streetAddress":"naist street","city":"Nara","postalCode":"630-0192"}
,
"phoneNumbers":[
{"type":"iPhone","number":"0123-4567-8888"}
,
{"type":"home","number":"0123-4567-8910"}
]
}

Following are the responses for the expressions after evaluating the array expressions in JSON path.

Expressions Response
$.phoneNumbers[1].type "home"
$.phoneNumbers[0,1].type or $.phoneNumbers[:2].type ["iPhone","home"]
$.phoneNumbers[0,1] or $.phoneNumbers[:2] [{"type":"iPhone","number":"0123-4567-8888"}\{"type":"home","number":"0123-4567-8910"}]
$..firstName ["John"]
$.firstName "John"
$.address.city "Nara"

System Context Variables

API Gateway provides predefined system context variables and the values of these variables are extracted from the client request.

Variable Syntax Description
${apiId} Get the value of the API ID.
${apiName} Get the name of the API.
${apiVersion} Get the version of the API.
${packageId} Get the value of the package ID.
${planId} Get the value of the plan ID.
${customTransactionFields.FIELD_NAME}
Example: ${customTransactionFields.sample}
Provides you an option to get or set custom fields to the transactional events for this request. To set the custom fields, you can configure the customTransactionFields.FIELD_NAME custom variable in Custom Extension policy.
${providerTime} Gets the time taken in milliseconds between the request sent to native server and response received from native server for this transaction.
${date} Gets the date when the request gets invoked.
${dynamicEndpoint} Gets the value of the ROUTING_ENDPOINT context variable set using pub.apigateway.ctxvar:setContextVariable
${time} Gets the time when the request gets invoked.
${inboundHttpMethod}
Example: GET
Gets the value the HTTP method used by the client to send the request.
${routingMethod}
Example: POST
Gets the value of the HTTP method used by the API Gateway in the routing policy to send the request to native API.
${InboundContentType}
Example: application/json
Gets the content type of the request.
${inboundAccept}
Example: */*
Gets the accept header in the incoming request from the client.
${inboundProtocol} Gets the protocol of the request.
${inboundRequestURI}
For example, if the API is invoked: http://hostname/gateway/API then the expected value of this variable would be /gateway/API.
For a REST API, the URL also includes query string parameters.
For example, if the following API is invoked: http://hostname/gateway/cars?vin=1234 the expected value of this variable would be /gateway/cars?vin1234.
A partial reference to an API (for HTTP and HTTPS only). The protocol, host are not part of the value.
${inboundIP}
Example: 210.178.9.0
Gets the value of the client IP address used to send the request.
${gatewayHostname}
Example: uk.myhost.com
Gets the API Gateway host name.
${gatewayIP}
Example: 198.168.1.9
Gets API Gateway IP address.
${operationName}
Example: addInts
Gets the value of API operation selected from the request. Operation names are available only for SOAP APIs. It is empty for REST API.
${nativeEndpoint}
Example: http://hostname/Service
Gets the value of the native endpoints from the request. It returns value only after executing the routing policy.

Enhancements to Variable Framework Support

Until API Gateway version 10.5, the variable framework was supported in API Mashup, Request Transformation, Response Transformation, Conditional Error Processing, and Custom Extension policies.

In API Gateway version 10.7 the existing variable framework is enhanced to support the following use cases:

Note: As like the earlier versions of API Gateway, you can also define and access the custom-context variable or custom-variable using the ctxVar IS Service. For details, see The API for Context Variables.

Transport

The policies in this stage specify the protocol to be used for an incoming request and the content type for a REST request during communication between API Gateway and an application. The policies included in this stage are:

Enable HTTP/HTTPS

This policy specifies the protocol to use for an incoming request to the API on API Gateway. If you have a native API that requires clients to communicate with the server using the HTTP and HTTPS protocols, you can use the Enable HTTP or HTTPS policy. This policy allows you to bridge the transport protocols between the client and API Gateway.

For example, you have a native API that is exposed over HTTPS and an API that receives requests over HTTP. If you want to expose the API to the consumers of API Gateway through HTTP, then you configure the incoming protocol as HTTP.

The table lists the properties that you can specify for this policy:

Parameter Description
Protocol Specifies the protocol (HTTP or HTTPS) and SOAP format (for a SOAP-based API) to be used to accept and process the requests.

Select one of the following:
  • HTTP. API Gateway accepts requests that are sent using the HTTP protocol. This is selected by default.

  • HTTPS. API Gateway accepts requests that are sent using the HTTPS protocol.
SOAP Version For SOAP-based APIs.
Specifies the SOAP version of the requests which the API Gateway accepts from the client.

Select one of the following:
  • SOAP 1.1. This is selected by default. API Gateway accepts requests that are in the SOAP 1.1 format.

  • SOAP 1.2. API Gateway accepts requests that are in the SOAP 1.2 format.

Set Media Type

This policy specifies the content type for a REST request. If the content type header is missing in a client request sent to an API, API Gateway adds the content type specified here before sending the request to the native API.

The table lists the properties that you can specify for this policy:

Parameter Description
Default Content-Type Specifies the default content type for REST request received from a client.

Examples for content types: application/json, application/xml.
Default Accept Header Specifies the default accept header for REST request received from a client.

As both these properties support variable framework, you can use the available variables to specify the content type and accept header. For details about the variables available in API Gateway, see Variables Available in API Gateway.

Identify and Access

The policies in this stage provide different ways of identifying and authorizing the application, and provide the required access rights for the application. The policies included in this stage are:

The Inbound authentication policies are used to authenticate the application by specifying user-based SPN or host-based SPN for a Kerberos token, using the basic credentials for the HTTP basic authentication or through various token assertions or through the XML security actions.

The Identify and Authorize Application policy is used to identify the application, authenticate the request based on policy configured and authorizes it against all applications registered in API Gateway.

Inbound Auth - Message

An API Provider can use this policy to enforce authentication on the API. When this policy is configured for an API, API Gateway expects the clients to pass the authentication credentials through the payload message that will be added to the request and sent to the native API. API Gateway supports a wide range of authentication schemes, such as X.509 Certificate, WSS Username, SAML, and Kerberos, in addition to signing and encryption, at the message-level.

Note: Message-level authentication can be used to secure inbound communication of only SOAP APIs.

The table lists the properties that you can specify for this policy:

Parameter Description
Binding Assertion Specifies the type of binding assertion required for the message transfer between the recipient and the initiator.
Require Encryption. Specifies that a request's XML element, which is represented by an XPath expression or by parts of a SOAP request such as the SOAP body or the SOAP headers, be encrypted.
Encrypted Parts Click + Add encrypted part to add the required properties. This allows you to encrypt parts of a SOAP request such as the SOAP body or the SOAP headers.

Provide the following information:

  • Entire SOAP Body. Specifies encryption of the entire SOAP body.
  • All SOAP Attachments. Specifies encryption of all the SOAP attachments.

In the SOAP Header section, provide the following information:

  • Header Name. Specifies the name for the SOAP header field.
  • Header Namespace. Specifies the namespace of the SOAP header to be encrypted.

You can add more SOAP headers by clicking icon.

Encrypted Elements Click + Add encrypted element to add the required properties. Select this option to encrypt the entire element, which is represented by an XPath expression.

Provide the following information:

XPath. Specifies the XPath expression in the API request.

In the Namespace section, provide the following information:

  • Namespace Prefix. Specifies the namespace prefix of the element to be encrypted.
  • Namespace URI. Specifies the generated XPath element.

You can add more namespace prefixes and URIs by clicking icon.

Require Signature. Specifies that a request's XML element, which is represented by an XPath expression or by parts of a SOAP request such as the SOAP body or the SOAP headers, be signed.
Signed Elements Click + Add require signature to add the required properties. Select this option to sign the entire element represented by an XPath expression.

Provide the following information:

XPath. Specifies the XPath expression in the API request.

For the Namespace section, provide the following information:

  • Namespace Prefix. Specifies the namespace prefix of the element to be signed.
  • Namespace URI. Specifies the generated XPath element.

You can add more namespace prefixes and URIs by clicking icon.

Signed Parts Click + Add signed part to add the required properties. Select this option to sign parts of a SOAP request such as the SOAP body or the SOAP headers.

Provide the following information:

  • Entire SOAP Body. Specifies signing of the entire SOAP body.
  • All SOAP Attachments. Specifies signing of all the SOAP attachments.

For the SOAP Header section, provide the following information:

  • Header Name. Specifies the name for the SOAP header field.
  • Header Namespace. Specifies the Namespace of the SOAP header to be signed.

You can add more namespace prefixes and URIs by clicking icon.

Match Criteria Select one of the following options:
  • Allow Sublevels. Any one of the audience URI in the incoming SAML assertion either has to be an exact match or it can have sub paths to the configured URI. For example, if http://yahoo.com is configured as the URI and the Allow Sublevels option is selected, the audience URI has http://yahoo.com/mygroup and condition is matched because the main URI matches with the configured URI (http://yahoo.com). The extra path mygroup is a sublevel path.
  • Exact match. Any one of the audience URI in the incoming SAML assertion is verified for the exact match with the configured URI. For example, if http://yahoo.com is configured as the URI and the Exact match option is selected, the audience URI must be configured with http://yahoo.com in order to match the condition. This is selected by default.

For more information on audience URI, see conditions and audience restriction sections in the SAML specification available in the https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf location.

Token Assertions Select the type of token assertion required to authenticate the client.

Select any of the following:

  • Require X.509 Certificate. Mandates that there should be a wss x.509 token in the incoming SOAP request.
  • Require WSS Username token. Mandates that there should be a WSS username token in the incoming SOAP request. Uses WS-Security authentication to validate user names and passwords that are transmitted in the SOAP message header for the WSS Username token.
  • Kerberos Token Authentication. Mandates that there should be a Kerberos token in the incoming SOAP request. Authenticates the client based on the Kerberos token. API Gateway extracts the Kerberos token from the SOAP body and validates the token with the KDC using SPN credentials configured by the provider for the API. If the Kerberos token sent by the client is valid, API Gateway forwards the request to the native service and the response to the client.
    • Service Principal Name. Specifies a valid SPN, which is the name type to use while authenticating an incoming client principal name. The specified value is used by the client or the server to obtain a service ticket from the KDC server.
      Note: API Gateway supports the username format for Service Principal Names (SPNs). This format represents the principal name as a named user defined in LDAP used for authentication to the KDC.
    • Service Principal Password. Specifies a valid password of the Service Principal Name user or the Service Principal Name host.

  • Custom Token Assertion. Type a search string, select a custom token assertion name to authenticate the client, and click icon to add. You can add more custom token assertions in a similar way.

    Click the Custom Token Assertion arrow to see a list of all custom token assertions available in API Gateway.

    Click icon to delete the custom token assertion added.

Require Timestamp Specifies that the time stamps be included in the request header. API Gateway checks the time stamp value against the current time to ensure that the request is not an old message. This serves to protect your system against attempts at message tampering, such as replay attacks.

Identify & Authorize

This policy identifies and validates the authorization of the applications to access the APIs. The applications are identified using a set of identification types such as API key, hostname address, and HTTP basic authentication and so on based on the configuration. API Gateway can identify and authorize the application based on the following Application Lookup condition:

Note: If Allow anonymous is selected and even if the Application Lookup condition does not meet, API Gateway allows access to the API.

The table lists the properties that you can specify for this policy:

Parameter Description
Condition Specifies the condition operator for the identification and authentication types.

Select any of the following condition operators:
  • AND. Applies all the identification and authentication types.
  • OR. Applies one of the selected identification and authentication types.
Note: Even though this policy provides the option of choosing an AND or OR operation between the different identification and authentication types, the operation across the different policies in the IAM stage is always AND.
Allow anonymous Specifies whether to allow all users to access the API without restriction.

When you add a security policy and configure Allow anonymous, all requests are allowed to pass through to the native API, but the successfully identified requests are grouped under the respective identified application, and all unidentified requests are grouped under a common application named asDefaultApplication (Sys:defaultApplication). While you allow all requests to pass through you can perform all application-specific actions, such as, viewing the runtime events for a particular application, monitor the service level agreement for a few applications and send an alert email based on some criteria like request count or availability, and throttle the requests from a particular application and not allow the request from that application if the number of requests reach the configured hard limit within configured period of time.

Identification Type. Specifies the identification type. You can select any of the following.
API Key Specifies using the API key to identify and validate the client's API key to verify the client's identity in the registered list of applications for the specified API.

Select one of the Application Lookup condition:

  • Registered applications. Identifies the client's API key against the API key of all the applications registered to the API. On successful identification, API Gateway allows access to the API.
  • Global applications. Identifies the client's API key against the API key of all the applications available in API Gateway. On successful identification, API Gateway allows access to the API.
  • Global applications and Default Application. Identifies the client's API key against all the applications available in API Gateway. Even though, if no global application is identified, API Gateway allows access to the API as default application.
  • When this option is selected, you can use the API key as:

    • Header parameter to consume an API. For example,

      x-Gateway-APIKey:a4b5d569-2450-11e3-b3fc-b5a70ab4288a

    • Query parameter to invoke a API resource. For example,

      http://pie-3HKYMH2:5555/gateway/PetstoreAPI/1.0.3/store/inventory?APIKey=faab7ac6-97a4-4228-908d-f1930faba470

Hostname Address Specifies using host name address to identify the client, extract the client's hostname from the HTTP request header and verify the client's identity in the specified list of applications in API Gateway.

Select one of the Application Lookup condition:

  • Registered applications. Identifies the client's hostname against the hostname identifier of all the applications registered to the API. On successful identification, API Gateway allows access to the API.
  • Global applications. Identifies the client's hostname against the hostname identifier of all the applications available in API Gateway. On successful identification, API Gateway allows access to the API.
  • Global applications and DefaultApllication. Identifies the client's hostname against the hostname identifier of all the applications available in API Gateway. If no global application is identified, then API Gateway allows access to the API as default application.
  • Note: If the client request has X-Forwarded-For header, then API Gateway resolves the hostname from the IP address present in the X-Forwarded-For header. Else, API Gateway resolves the hostname from the client's IP address.

HTTP Basic Authentication Specifies using Authorization Header in the request to identify and authorize the client application against the list of applications with the identifier username in API Gateway.

Provide the following information:

Select one of the Application Lookup condition:

  • Registered applications. Authenticates the user and identifies the user against username identifier of all the applications registered to the API. On successful authentication and identification, API Gateway allows access to the API.
  • Global applications. Authenticates the user and identifies the user against username identifier of all the applications available in the API Gateway. On successful authentication and identification, API Gateway allows access to the API.
  • Global applications and DefaultApplication.
    1. Authenticates the user and identifies the user against username identifier of all the applications available in the API Gateway.
    2. On successful authentication and if no global application is identified, then API Gateway allows access to the API as default application.
    3. In case if the authentication fails, then API Gateway does not allow access to the API.
  • If Global applications and DefaultApplication and Allow anonymous are selected:
    1. Authenticates the user and identifies the user against username identifier of all the applications available in the API Gateway.
    2. On successful authentication and if no global application is identified, then API Gateway allows access to the API as default application.
    3. In case if the authentication fails, then API Gateway still allows access to the API.
Important: If an external IDP (Identity Provider)is configured to authenticate the users in Software AG Cloud and if you have enforced HTTP Basic Authentication policy for an API, API Gateway will not be able to authenticate since the user is not local to Software AG Cloud. As a workaround, the corresponding users can be created in Software AG Cloud, so that API Gateway can authenticate the local users.
IP Address Range Specifies using the IP address range to identify the client, extract the client's IP address from the HTTP request header, and verify the client's identity against the specified list of applications in API Gateway.

Select one of the Application Lookup condition:

  • Registered applications. Identifies the client's IP address against the IP address range identifier of all the applications registered to the API. On successful identification, API Gateway allows access to the API.
  • Global applications. Identifies the client's IP address against the IP address range identifier of all the applications available in API Gateway. On successful identification, API Gateway allows access to the API.
  • Global applications and DefaultApplication. Identifies the client's IP address against the IP address range identifier of all the applications available in API Gateway. If no global application is identified, then API Gateway allows access to the API as default application.
Note: If the client request has X-Forwarded-For header, then API Gateway uses the IP address present in the X-Forwarded-For header. Else, API Gateway uses the client's IP address for identification.

JWT Specifies using the JSON Web Token (JWT) to identify the client, extract the claims from the JWT and validate the client's claims, and verify the client's identity against the specified list of applications in API Gateway.

Select one of the Application Lookup condition:

  • Registered applications. Identifies the JWT against the claims identifier of all the applications registered to the API. On successful identification, API Gateway allows access to the API.
  • Global applications. Identifies the JWT against the claims identifier of all the applications available in API Gateway. On successful identification, API Gateway allows access to the API.
  • Global applications and DefaultApplication. Identifies the JWT against the claims identifier of all the applications available in API Gateway. If no global application is identified, then API Gateway allows access to the API as default application.
Note:
  • You can use the claims in the JWT for further processing using request transformation policy.
  • When a Policy violation event is logged in case of expired JWT tokens, the application is associated as the identified application since the identification happens before the expiry is checked.
Kerberos Token Specifies using the Kerberos token to identify the client, extract the client's credentials from the Kerberos token, and verify the client's identity against the specified list of applications in API Gateway.

Note: You have to enforce the Inbound Authentication - Message policy with the property, Kerberos Token Authentication, configured, so when Identify and Authorize Application policy is executed, the user details fetched are used to match with application's data to identify the application.

Select one of the Application Lookup condition:

  • Registered applications. Authenticates the incoming Kerberos token and identifies the user against the username identifier of all the applications registered to the API. On successful authentication and identification, API Gateway allows access to the API.
  • Global applications. Authenticates the incoming Kerberos token and identifies the user against the username identifier of all the applications available in API Gateway. On successful authentication and identification, API Gateway allows access to the API.
  • Global applications and DefaultApplication.
    1. Authenticates the incoming Kerberos token and identifies the user against username identifier of all the applications available in the API Gateway.
    2. On successful authentication and if no global application is identified, then API Gateway allows access to the API as default application.
    3. In case if the authentication fails, then API Gateway does not allow access to the API.
  • If Global applications and DefaultApplication and Allow anonymous are selected:
    1. Authenticates the incoming Kerberos token and identifies the user against username identifier of all the applications available in the API Gateway.
    2. On successful authentication and if no global application is identified, then API Gateway allows access to the API as default application.
    3. In case if the authentication fails, then API Gateway still allows access to the API.
Note: You can use the username for further processing using the request transformation policy.
OAuth2 Token Specifies using the OAuth2 token to identify the client, extract the access token from the HTTP request header, and verify the client's identity against the specified list of applications in API Gateway.

By default, OAuth2 token is identified against the registered applications.

Note:
  • You can use the client id and other parameters for further processing using the request transformation policy
  • When a Policy violation event is logged in case of expired Oauth2 tokens, the application that is associated turn in to Unknown
.
OpenID Connect Specifies using the OpenID (ID) token to identify the client, extract the client's credentials from the ID token, and verify the client's identity against the specified list of applications in API Gateway.

Select one of the Application Lookup condition:

  • Registered applications. Identifies the client's identity resolved as part of OpenID validation against all the applications registered to the API. On successful identification, API Gateway allows access to the API.
  • Global applications. Identifies the client's identity resolved as part of OpenID validation against all the applications available in API Gateway. On successful identification, API Gateway allows access to the API.
  • Global applications and DefaultApplication. Identifies the client's identity resolved as part of OpenID validation against all the applications available in API Gateway. If no global application is identified, then API Gateway allows access to the API as default application.
Note: You can use the client id and other parameters for further processing using the request transformation policy.
SSL Certificate Specifies using the SSL certificate to identify the client, extract the client's identity certificate, and verify the client's identity (certificate-based authentication) against the specified list of applications in API Gateway. The client certificate that is used to identify the client is supplied by the client to API Gateway during the SSL handshake over the transport layer or is added in the header of the request.

The certificate included in the custom header can be in the following formats:

  • Base64 encoded PEM certificate with BEGIN CERTIFICATE and END CERTIFICATE delimiters
  • Non-Base64 encoded PEM certificate with BEGIN CERTIFICATE and END CERTIFICATE delimiters
  • PEM certificate can be without BEGIN CERTIFICATE and END CERTIFICATE delimiters if a single certificate is added.
  • URL encoded PEM certificate with BEGIN CERTIFICATE and END CERTIFICATE delimiters.
  • URL encoded PEM certificate can be without the BEGIN CERTIFICATE and END CERTIFICATE delimiters if a single certificate is added.

If the transport protocol is HTTP then API Gateway checks for the existence of a header and fetches the certificate from the certificate header. If the certificate is coming from the custom header, then API Gateway does not check the validity of the certificate. API Gateway identifies the application using the certificate. The certificate should be validated by some external entity before sending it to API Gateway in a custom header.

If the transport protocol is HTTPS then API Gateway first tries to identify the application based on the certificate exposed by the client during the SSL handshake. If there is no client certificate or the identification based on the client certificate fails, API Gateway tries to identify based on the certificate provided in the header.

The header name is customizable and can be customized in the extended settings property, customCertificateHeader, the default value being X-Client-Cert.

Select one of the Application Lookup condition:

  • Registered applications. Identifies the client's certificate against the client certificate identifier of all the applications registered to the API. On successful identification, API Gateway allows access to the API.
  • Global applications. Identifies the client's certificate against the client certificate identifier of all the applications available in API Gateway. On successful identification, API Gateway allows access to the API.
  • Global applications and DefaultApplication. Identifies the client's certificate against the client certificate identifier of all the applications available in API Gateway. If no global application is identified, then API Gateway allows access to the API as default application.
WS Security Username Token This is applicable only for SOAP APIs.

Specifies using the WS security username token to identify the application, extract the client's credentials (username token and password) from the WSSecurity SOAP message header, and verify the client's identity against the specified list of applications in API Gateway.

Note: You have to enforce the Inbound Authentication - Message policy with the property, Require WSS Username token, configured, so when Identify and Authorize Application policy is executed, the user details fetched are used to match with application's data to identify the application.

Select one of the Application Lookup condition:

  • Registered applications. Authenticates the client's WSS username token and identifies the user against theusername identifier of all the applications registered to the API. On successful authentication and identification, API Gateway allows access to the API.
  • Global applications. Authenticates the client's WSS username token and identifies the user against theusername identifier of all the applications available in API Gateway. On successful authentication and identification, API Gateway allows access to the API.
  • Global applications and DefaultApplication.
    1. Authenticates the client's WSS username token and identifies the user against the username identifier of all the applications available in the API Gateway.
    2. On successful authentication and if no global application is identified, then API Gateway allows access to the API as default application.
    3. In case if the authentication fails, then API Gateway does not allow access to the API.
  • If Global applications and DefaultApplication and Allow anonymous are selected:
    1. Authenticates the client's WSS username token and identifies the user against the username identifier of all the applications available in API Gateway.
    2. On successful authentication and if no global application is identified, then API Gateway allows access to the API as default application.
    3. In case if the authentication fails, then API Gateway still allows access to the API.
Note: You can use the username for further processing using the request transformation policy.
WS Security X.509 Certificate This is applicable only for SOAP APIs.

Specifies using the WS security X.509 certificate to identify the client, extract the client identity certificate from the WS-Security SOAP message header, and verify the client's identity against the specified list of applications in API Gateway.

Note: You have to enforce the Inbound Authentication - Message policy with the property, Require X.509 Certificate, configured, so when Identify and Authorize Application policy is executed, the user details fetched are used to match with application's data to identify the application.

Select one of the Application Lookup condition:

  • Registered applications. Identifies the client's X.509 certificate against the client certificate identifier of all the applications registered to the API. On successful identification, API Gateway allows access to the API.
  • Global applications. Identifies the client's X.509 certificate against the client certificate identifier of all the applications available in API Gateway. On successful identification, API Gateway allows access to the API.
  • Global applications and DefaultApplication. Identifies the client's X.509 certificate against the client certificate identifier of all the applications available in API Gateway. If no global application is identified, then API Gateway allows access to the API as default application.
Payload Element Specifies using the payload identifier to identify the client, extract the custom authentication credentials supplied in the request represented using the payload identifier, and verify the client's identity against the specified list of applications in API Gateway.

Select one of the Application Lookup condition:

  • Registered applications. Identifies the client's payload against the Payload Identifier of all the applications registered to the API. On successful identification, API Gateway allows access to the API.
  • Global applications. Identifies the client's payload against the Payload Identifier of all the applications available in API Gateway. On successful identification, API Gateway allows access to the API.
  • Global applications and DefaultApplication. Identifies the client's payload against the Payload Identifier of all the applications available in API Gateway. If no global application is identified, then API Gateway allows access to the API as default application.

In the Payload identifier section, click Add payload identifier, provide the following information, and click Add.

  • Expression type: Specifies the type of expression, which is used for identification. You can select one the following expression type:
    • XPath. Provide the following information:
      • Payload Expression. Specifies the payload expression that the specified expression type in the request has to be converted to. For example: /name/id
      • Namespace Prefix. The namespace prefix of the payload expression to be validated.
      • Namespace URI. The namespace URI of the payload expression to be validated.
      Note: You can add multiple namespace prefix and URI by clicking .
    • JSONPath. Provide the JSONPath for the payload identification. For example, $.name.id
    • Text. Provide the regular expression for the payload identification. For example, any valid regular expression.

You can add multiple payload identifiers as required.

Note: Only one payload identifier of each type is allowed. For example, you can add a maximum of three payload identifiers, each being of a different type.
HTTP Headers Specifies using any header in the request to identify and authorize the client application against the list of applications with the identifier in API Gateway.

Provide the following information:

  • Select one of the Application Lookup condition:
    • Registered applications. Identifies the client's header against the Header Key - Value pair identifier of all the applications registered to the API. On successful identification, API Gateway allows access to the API.
    • Global applications. Identifies the client's header against the Header Key - Value pair identifier of all the applications available in API Gateway. On successful identification, API Gateway allows access to the API.
    • Global applications and DefaultApplication. Identifies the client's header against the Header Key - Value pair identifier of all the applications available in API Gateway. If no global application is identified, then API Gateway allows access to the API as default application.

Request Processing

These policies are used to specify how the request message from an application has to be transformed or pre-processed and configure the masking criteria for the data to be masked before it is submitted to the native API. This is required to protect the data and accommodate differences between the message content that an application is capable of submitting and the message content that a native API expects. The policies included in this stage are:

Invoke webMethods IS

This policy pre-processes the request messages and transforms the message into the format required by the native API or performs some custom logic, before API Gateway sends the requests to the native APIs.

For example, you might need to accommodate differences between the message content that a client is capable of submitting and the message content that a native API expects. For example, if the client submits an order record using a slightly different structure than the structure expected by the native API, you can use this action to process the record submitted by the client to the structure required by the native API.

If Comply to IS Spec parameter is configured as true, API Gateway invokes the IS Service with IS specification in the path pub.apigateway.invokeISService.specifications:RequestSpec for Request Processing

The following are the input and output parameters for REST, and SOAP APIs as specified in the above IS Specification:

API type Input parameters Output parameters
REST
  • headers
  • query
  • payload
  • path
  • httpMethod
  • messageContext
  • apiName
  • apiVersion
  • requestUrl
  • correlationID (this is unique for request and response)
  • headers
  • query
  • payload
  • path
  • httpMethod
  • messageContext
  • SOAP
    • headers
    • payload
    • messageContext
    • apiName
    • payloadObject
    • requestUrl
    • correlationID (this is unique for request and response)
  • headers
  • payload
  • messageContext
  • payloadObject
  • If Comply to IS Spec parameter is set to false, API Gateway invokes the IS Service with the same input and output parameters supported in 10.1 and the earlier versions:

    The table lists the properties that you can specify for this policy:

    Parameter Description
    Invoke webMethods Integration Server Service
    Add invoke webMethods Integration Server service Specifies the webMethods IS service to be invoked to pre-process the request messages and the authentication mode for the IS service.

    Provide the following information:

    • webMethods IS Service. Specify the webMethods IS service to be invoked to pre-process the request messages.
      The webMethods IS service must be running on the same Integration Server as API Gateway.
      Note: If an exception occurs when invoking the webMethods IS service, by default API Gateway displays the status code as 500 and error message as Internal Server Error.
      You can set custom status code and error message by setting the following properties in the message context of the webMethods IS service:
      • service.exception.status.code
      • service.exception.status.message
      The sample code is given below:
      IDataCursor idc = pipeline.getCursor();MessageContext context = (MessageContext)IDataUtil.get(idc,"MessageContext");if(context != null){context.setProperty"service.exception.status.code", 404);context.setProperty("service.exception.status.message", "Object Not Found");throw new ServiceException(); }
    • Comply to IS Spec. Mark this as true if you want the input and the output parameters to comply to the IS Spec present in pub.apigateway.invokeISService.specifications folder in wmAPIGateway package.
      Note: Software AG recommends users to configure the policy with Comply to IS Spec as true, as you can read or change the values of headers, and so on, without having to read from or write to the message context.
    webMethods IS Service alias Specifies the webMethods IS service alias to be invoked to pre-process the request messages.

    Start typing the webMethods alias name, select the alias from the type-ahead search results displayed and click icon to add one or more aliases.

    You can use the delete icon icon to delete the added aliases from the list.

    Request Transformation

    This policy enables you to configure several transformations on the request messages from clients into a format required by the native API before it is submitted to the native API.

    The transformations include Header, Query Parameter, Path Parameter transformation, HTTP Method transformation, Payload transformation, and Advanced transformation. You can configure conditions according to which the transformations are executed.

    The table lists the properties that you can specify for this policy:

    Parameter Description
    Condition Conditions are used to specify when the policy has to be executed. You can add multiple conditions with logical operators.
    Available values are:
    • AND. API Gateway transforms the requests that comply with all the configured conditions.
    • OR. This is selected by default. API Gateway transforms the requests that comply with any one configured condition.
    Click Add Condition and provide the following information and click icon.
    • Variable: Specifies the variable type with a syntax.
    • Operator: Specifies the operator to use to relate variable and the value provided. You can select one of the following:
      • Equals
      • Equals ignore case
      • Not equals
      • Not equals ignore case
      • Contains
      • Not Contains
      • Exists
      • Not Exists
      • Range
      • Greater Than
      • Less Than
    • Value: Specifies a plain value or value with a syntax.

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

    Transformation Configuration. Specifies various transformations to be configured.
    Header/Query/Path Transformation for REST API

    and

    Header Transformation for SOAP API

    Specifies the Header, Query or path transformation to be configured for incoming requests.

    You can add or modify header, query or path transformation parameters by providing the following information:

    • Variable. Specifies the variable type with a syntax.
    • Value: Specifies a plain value or value with a syntax.

    You can add multiple variables and corresponding values by clicking icon.

    You can remove any header, query, or path transformation parameters by typing the plain value or value with a syntax.

    Note: Software AG recommends you not to modify the headers ${request.headers.Content-Length} and ${request.headers.Content-Encoding} as API Gateway adds the right values for these headers before sending the response back to client.

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

    Note: Payload transformation does not happen automatically for content-type transformation. When you change the content type, ensure that you do payload transformation. For example, if you change the content-type header from application/xml to application/json, you must also change the respective payload from application/xml to application/json.
    Method transformation for REST API Specifies the method transformation to be configured for incoming requests.
    Select any of the HTTP Method listed:
    • GET
    • POST
    • PUT
    • DELETE
    • HEAD
    • CUSTOM
    Note: When CUSTOM is selected, the HTTP method in 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: Only Method Transformation happens when configured, but you have to take care of adding payload during transformations involving method change like GET to POST, and so on.
    Payload Transformation Specifies the payload transformation to be configured for incoming requests.
    Provide the following information:
    • Payload Type. Specifies the content-type of payload, to which you want to transform. The Payload field renders the respective payload editor based on the selected content-type.
    • Payload. Specifies the payload transformation that needs to be applied for the incoming requests
    • As this property supports variable framework, you can make use of the available variables to transform the request messages.

      For example, consider the native API accepting two integer values value1 and value2, and you want to pass these two values from API Gateway to the native API, you can configure the payload field as follows:

      {"value1" : 12,"value2" : 34}

      You can also configure the payload field using one or more variables by using variable framework. Let us see another syntax. For example, for the same native API seen in the previous example, if your client sends both the values through headers val1 and val2, and you want to add it to payload for the native API to recognize the input, you can do so by configuring the payload field as follows:

      {"value1" :${request.headers.val1},"value2" :${request.headers.val2}}
      For details about the variables available in API Gateway, see Variables available in API Gateway.
      Note: If your payload content-type is different from the incoming payload's content-type, you need to transform the content-type of the header using Header Transformation.
    • Click + Add xslt document to add an xslt document and provide the following information:
      • XSLT file. Specifies the XSLT file used to transform the request messages as required.

        Click Browse to browse and select a file.

      • Feature Name. Specifies the name of the XSLT feature.
      • Feature value. Specifies the value of the XSLT feature.

        You can add more XSLT features and xslt documents by clicking icon.

      Note:API Gateway supports XSLT 1.0 and XSLT 2.0.
    • Click + Add xslt transformation alias and provide the following information:
      • XSLT Transformation alias. Specifies the XSLT transformation alias

        When the incoming request is in JSON, you can use a XSLT file similar to the below sample:

        
        <?xml version="1.0" ?>
        <xsl:stylesheet version="1.1"
        xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
        <xsl:output method="xml"/>
        <xsl:template match="/" >
        <xsl:element name="fakeroot">
        <xsl:element name="fakenode">
        <!-- Apply your transformation rules based on the request
        from the Client-->
        </xsl:element>
        </xsl:element>
        </xsl:template>
        </xsl:stylesheet>

        When the incoming request is in XML, you can use a XSLT file similar to the below sample:

        
        <?xml version="1.0" ?>
        <xsl:stylesheet version="1.1"
        xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
        xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
        <xsl:output method="xml"/>
        <xsl:template match="/">
        <xsl:element name="soapenv:Envelope">
        <xsl:element name="soapenv:Body">
        <!-- Apply your transformation rules
        based on the request from the Client-->
        </xsl:element>
        </xsl:element>
        </xsl:template>
        </xsl:stylesheet>
    Advanced Transformation Specifies the advanced transformation to be configured for incoming requests.
    Provide the following information:
    • webMethods IS Service. Specify the webMethods IS service to be invoked to process the request messages. The list displays only the pre-shipped Integration Server services, which you can invoke to pre-process or post-process the request message.

      You can add multiple services by clicking icon.

    • Comply to IS Spec. Mark this as true if you want the input and the output parameters to comply to the IS Spec present in pub.apigateway.invokeISService.specifications folder in wmAPIGateway package.
    • webMethods IS Service alias. Specifies the webMethods IS service alias to be invoked to pre-process the request messages.
    Transformation Metadata. Specifies the metadata for transformation of the incoming requests. For example, the namespaces configured in this section can be used when you provide the syntax for XPath ${request.payload.xpath} For example: ${request.payload.xpath[//ns:emp/ns:empName]}
    Namespace Specifies the namespace information to be configured for transformation.
    Provide the following information:
    • Namespace Prefix. The namespace prefix of the payload expression to be validated.

      For example, specify the namespace prefix as SOAP_ENV.

    • Namespace URI. The namespace URI of the payload expression to be validated.

      For example, specify the namespace URI as http://schemas.xmlsoap.org/soap/envelope/. This declaration defines SOAP_ENV as an alias for the namespace: http://schemas.xmlsoap.org/soap/envelope/.

      Note: You can add multiple namespace prefix and URI by clicking icon.

    Validate API Specification

    This policy validates the incoming request against API’s various specifications such as schema, query parameters, path parameters, content-types, and HTTP Headers referenced in their corresponding formats as follows:

    The request sent to the API by an application must conform with the structure or format expected by the API. The incoming requests are validated against the API specifications in this policy to conform to the structure or format expected by the API.

    Various API specifications validated are:

    The runtime invocations that fail the specification validation are considered as policy violations. You can view such policy violation events in the dashboard.

    The table lists the API specification properties, you can specify for this policy, to be validated:

    Parameter Description
    Schema Validates the response payload against the appropriate schema (based on the Content-type header in request or Accept header in response). Provide the following additional features for XML schema validation:
    • Feature name. Specifies the name of the feature for XML parsing when performing XML schema validation.

    • Select the required feature names from the list:
      • GENERATE_SYNTHETIC_ANNOTATIONS
      • ID_IDREF_CHECKING
      • IDENTITY_CONSTRAINT_CHECKING
      • IGNORE_XSL_TYPE
      • NAMESPACE_GROWTH
      • NORMALIZE_DATA
      • ROOT_ELEMENT_DECL
      • ROOT_TYPE_DEF
      • SIGMA_AUGMENT_PSVI
      • SCHEMA_DV_FACTORY
      • SCHEMA_ELEMENT_DEFAULT
      • SCHEMA_LOCATION
      • SCHEMA_NONS_LOCATION
      • SCHEMA_VALIDATOR
      • TOLERATE_DUPLICATES
      • ENPARSED_ENTITY_CHECKING
      • VALIDATE_ANNOTATIONS
      • XML_SCHEMA_FULL_CHECKING
      • XMLSCHEMA_VALIDATION

      For details about XML parsing features, see http://xerces.apache.org/xerces2-j/features.html and for details about the exact constants, see https://xerces.apache.org/xerces2-j/javadocs/xerces2/org/apache/xerces/parsers/XML11Configuration.html.
    • Feature value. Specifies whether the feature value is True or False.
    Query Parameters This is applicable only for a REST API. Validates the query parameters in the incoming request against the query parameters defined in that request’s API Specification. The configuration is provided in the API details page.
    Path Parameters This is applicable only for a REST API. Validates the path parameters in the incoming request against the path parameters defined in that request’s API Specification. The configuration is provided in the API details page.
    Content-types Validates the content-types in the incoming response against the content-types defined in that response’s API Specification. The configuration is provided in the API details page.
    HTTP Headers Validates the HTTP header parameters in the incoming response against the HTTP headers defined in that response’s API Specification. The configuration is provided in the API details page. Provide the following information:
    • Condition. Specifies the logical operator to use to validate multiple HTTP headers in the incoming API responses.

    • Available values are:
      • AND. API Gateway accepts only the responses that contain all configured HTTP headers.
      • OR. This is selected by default. API Gateway accepts responses that contain at least one configured HTTP header.
    • HTTP Header Key. Specifies a key that must be passed through the HTTP header of the incoming API requests.
    • Header Value. Optional. Specifies the corresponding key value that could be passed through the HTTP header of the incoming API requests. As this property supports variable framework, you can make use of the available variables to specify the header value. For details about the variables available in API Gateway, see Variables available in API Gateway.

    • .
      You can add more HTTP headers by clicking icon

    Data Masking

    Data masking is a technique whereby sensitive data is obscured in some way to render it safe and to protect the actual data while having a functional substitute for occasions when the real data is not required.

    This policy is used to mask sensitive data at the application level. At the application level you must have an Identify and Access policy configured to identify the application for which the masking is applied. If no application is specified then it will be applied for all the other requests. Fields can be masked or filtered in the request messages received. You can configure the masking criteria as required for the XPath, JSONPath, and Regex expressions based on the content-type. This policy can also be applied at the API scope level.

    The table lists the content-type and masking criteria mapping.

    Content-type Masking Criteria
    application/xml
    text/xml
    text/htm
    XPath
    application/json
    application/json/badgerfish
    JSONPath
    text/plain Regex

    The table lists the masking criteria properties that you can configure to mask the data in the request messages received:

    Parameter Description
    Consumer Applications Optional. Specifies the applications for which the masking criterion has to be applied.

    Start typing the application name, select the application from the type-ahead search results displayed, and click icon to add one or more applications.

    For example: If there is a DataMasking(DM1) criteria created for application1 a second DataMasking(DM2) for application2 and a third DataMasking(DM3) with out any application, then for a request that comes from consumer1 the masking criteria DM1 is applied, for a request that comes from consumer2 DM2 is applied. If a request comes with out any application or from any other application except application1 and application2 DM3 is applied.

    You can use the delete icon icon** to delete the added applications from the list.

    XPath. Specifies the masking criteria for XPath expressions in the request messages.
    Masking Criteria Click Add masking criteria and provide the following information and click Add:
    • Query expression. Specify the query expression that has to be masked or filtered.

      For example: /pet/details/status, /user/details/card/ccnumber.

    • Masking Type. Specifies the type of masking required. You select either Mask or Filter. Selecting Mask replaces the value with the given value (the default value being ********). Selecting Filter removes the field completely.
    • Mask Value. Appears if you have select the Masking Type selected is Mask. Provide a mask value.
      You can add multiple masking criteria.

      As Query expression and Mask Value properties support variable framework, you can use the available variables.

      In case of query expression, if you provide variable syntax, the XPath is applied on the payload using the value that is resolved from the variable given.

      For example, if you provide a query expression as ${request.headers.myxpath} and the corresponding mask value as ${request.headers.var1} , and if the incoming request header myxpath is configured with value //ns:cardNumber, then the card number derived from the payload is masked with the header value in var1.

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

    • Namespace. Specifies the following Namespace information:
      • Namespace Prefix. The namespace prefix of the payload expression to be validated.
      • Namespace URI. The namespace URI of the payload expression to be validated
      Note: You can add multiple namespace prefix and URI by clicking icon.
    JSONPath. This is applicable only for REST API. Specifies the masking criteria for JSONPath expressions in the request messages.
    Masking Criteria Click Add masking criteria and provide the following information and click Add:
    • Query expression. Specify the query expression that has to be masked or filtered. For example: $.pet.details.status.
    • Masking Type. Specifies the type of masking required. You select either Mask or Filter. Selecting Mask replaces the value with the given value (the default value being ********). Selecting Filter removes the field completely.
    • Mask Value. Appears if you have select the Masking Type selected is Mask. Provide a mask value.
    • You can add multiple masking criteria.

      As Query expression and Mask Value properties support variable framework, you can use the available variables.

      In case of query expression, if you provide variable syntax, the JSONPath is applied on the payload using the value that is resolved from the variable given.

      For example, if you provide a query expression as ${request.headers.myjsonpath} and the corresponding mask value as ${request.headers.var1} , and if the incoming request header myjsonpath is configured with value $.cardNumber, then the card number derived from the payload is masked with the header value in var1.

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

    Regex. Specifies the masking criteria for regular expressions in the request messages.
    Masking Criteria Click Add masking criteria and provide the following information and click Add:
    • Query expression. Specify the query expression that has to be masked or filtered. For example: [0-9]+.
    • Masking Type. Specifies the type of masking required. You select either Mask or Filter. Selecting Mask replaces the value with the given value (the default value being ********). Selecting Filter removes the field completely.
    • Mask Value. Appears if you have select the Masking Type selected is Mask. Provide a mask value.
    • You can add multiple masking criteria.

      As Query expression and Mask Value properties support variable framework, you can use the available variables.

      In case of query expression, if you provide variable syntax, the regex is applied on the payload using the value that is resolved from the variable given.

      For example, if you provide a query expression as ${request.headers.myregex} and the corresponding mask value as ${request.headers.var1}, then the regex is applied using the value configured in the request header myregex and the derived value is masked with the header value in var1.

    For details about the variables available in API Gateway, see Variables available in API Gateway..
    Apply for transaction Logging Select this option to apply masking criteria for transactional logs.

    Note: For REST enabled SOAP services

    • Use JSONPath. To mask the incoming request of application/json content-type.
    • Use XPath of transformed SOAP request. To mask native service request.

    Apply for payload Select this option to apply masking criteria for request payload in the following scenarios:
    • Incoming request from the client.
    • Outgoing request to the native service.

    Routing

    The policies in this stage enforce routing of requests to target APIs based on the rules you can define to route the requests and manage their respective redirections according to the initial request path. The policies included in this stage are:

    In cases where the internal server is protected by a firewall, the endpoint in the routing policy that is applied should be configured as apigateway://registrationPort-aliasname/relative path of the API. Here the registration port alias name is the alias name configured for the external registration port to communicate with the internal port.

    Content-based Routing

    If you have a native API that is hosted at two or more endpoints, you can use the Content-based routing protocol to route specific types of messages to specific endpoints. You can route messages to different endpoints based on specific values that appear in the request message. You might use this capability, for example, to determine which operation the consuming application has requested, and route requests for complex operations to an endpoint on a fast machine. For example, if your entry protocol is HTTP or HTTPS, you can select the Content-based routing. The requests are routed according to the content-based routing rules you create. You may specify how to authenticate requests.

    Note: As the content-based routing policy’s capabilities can also be configured using conditional routing policy, the content-based routing policy will be deprecated in future releases and the configurations will be migrated to conditional routing policy. Hence, Software AG recommends to use conditional routing policy over content-based routing policy.

    The table lists the properties that you can specify for this policy:

    Parameter Description
    Default 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://hostname/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 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, 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 for 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: Software AG 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 API Gateway can use to parse SOAP requests to the native API.

    Select one of the following options:

    • MTOM. API Gateway uses the Message Transmission Optimization Mechanism (MTOM) to parse SOAP requests to the API.
    • SwA. API Gateway uses the SOAP with Attachment (SwA) technique to parse SOAP requests to the API.
    • None. 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 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 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 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 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 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 API Gateway uses the default value of 30 seconds.
    Pass WS-Security Headers This is applicable for SOAP-based APIs.

    Selecting this indicates that 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 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 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: A value for the path parameter. 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 registry) and the corresponding values for the path parameter as ${request.header.var1}, the value in var1 retrieved from the request header substitutes the service name.

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

    Rule. Defines the routing decisions based on one of the following routing options. Click Add Rule and provide the following information.
    Payload Identifier Specifies using the payload identifier to identify the client, extract the custom authentication credentials supplied in the request represented using the payload identifier, and verify the client's identity.

    In the Payload identifier section, click Add payload identifier, provide the following information, and click Add.

    • Expression type. Specifies the type of expression, which is used for identification. You can select one the following expression type:
      • XPath. Provide the following information:
        • Payload Expression. Specifies the payload expression that the specified XPath expression type in the request has to be converted to. For example: /name/id
        • Namespace Prefix. The namespace prefix of the payload expression to be validated.
        • Namespace URI. The namespace URI of the payload expression to be validated.
        Note: You can add multiple namespace prefix and URI by clicking icon.
      • JSONPath. Provide the Payload Expression that specifies the payload expression that the specified JSONPath expression type in the request has to be converted to. For example: $.name.id
      • Text. Provide the Payload Expression that specifies the payload expression that the specified Text expression type in the request has to be converted to. For example: any valid regular expression.

    You can add multiple payload identifiers as required.

    Note: Only one payload identifier of each type is allowed. For example, you can add a maximum of three payload identifiers, each being of a different type.
    Route To. Specifies the Endpoint URI of native APIs in a pool to which the requests are routed.
    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.

    For example, if your service is hosted at the URL: http://hostname/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 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, 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 for 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.

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

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

    Select one of the following options:

    • MTOM. API Gateway uses the Message Transmission Optimization Mechanism (MTOM) to parse SOAP requests to the API.
    • SwA. API Gateway uses the SOAP with Attachment (SwA) technique to parse SOAP requests to the API.
    • None. 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 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 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 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 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 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 API Gateway uses the default value of 30 seconds.
    Pass WS-Security Headers This is applicable for SOAP-based APIs.

    Selecting this indicates that 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.

    Provide the following information:

    • Keystore Alias. Specifies the keystore alias configured in 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 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: A value for the path parameter. 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 registry) and the corresponding values for the path parameter as ${request.header.var1}, the value in var1 retrieved from the request header substitutes the service name.

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

    Conditional Routing

    If you have a native API that is hosted at two or more endpoints, you can use the condition-based protocol to route specific types of messages to specific endpoints. The requests are routed according to the condition-based routing rules you create. For example, if your entry protocol is HTTP or HTTPS, you can select conditional routing specifying HTTP or HTTPS. A routing rule specifies where requests should be routed to, and the criteria to use to route. You may also specify how to authenticate requests.

    Note: The context-based routing policy is renamed and it’s capabilities are included in conditional routing policy. You can use this policy to configure to route the requests conditionally based on variable types.

    The following table provides the existing options of routing till API Gateway version 10.5 and their corresponding variable syntax to choose the same option in API Gateway version 10.7.

    10.5 Conditional Variable 10.5 Condition Operator 10.7 Transformation Variable 10.7 Transformation Condition Operator
    Consumer ${request.application.id} Equals
    Date Before After ${date} Lesser than Greater than
    Time Before After ${time} Lesser than Greater than
    Predefined System Context Variables
    Inbound HTTP Method Not equal to ${inboundHTTPMethod} Not equals
    Routing Method ${routingMethod}
    Inbound Content Type ${inboundContentType}
    Inbound Accept ${inboundAccept}
    Inbound Protocol ${inboundProtocol}
    Inbound Request URI ${inboundRequestURI}
    Inbound IP ${inboundIP}
    Gateway Hostname ${gatewayHostname}
    Gateway IP ${gatewayIP}
    Operation Name ${operationName}
    Custom Context Variables
    mx:var1 Equal to ${var1} Equals
    PROTOCOL_HEADERS[KEY] Not equal to ${request.headers.KEY} Not Equals
    SOAP_HEADERS[INDEX] Lesser than ${soapHeaders[INDEX} Lesser than
    Greater than Greater than
    IPV4 ${inboundIP} Range
    IPV6 ${inboundIP} Range

    The table lists the properties that you can specify for this policy:

    Parameter Description
    Default 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://hostname/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 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, 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: Software AG 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 API Gateway can use to parse SOAP requests to the native API.

    Select one of the following options:

    • MTOM.API Gateway uses the Message Transmission Optimization Mechanism (MTOM) to parse SOAP requests to the API.
    • SwA. API Gateway uses the SOAP with Attachment (SwA) technique to parse SOAP requests to the API.
    • None. 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 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 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 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 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 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 API Gateway uses the default value of 30 seconds.
    Pass WS-Security Headers This is applicable for SOAP-based APIs.

    Selecting this indicates that 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 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 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: A value for the path parameter. 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 registry) and the corresponding values for the path parameter as ${request.header.var1}, the value in var1 retrieved from the request header substitutes the service name.

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

    Rule. Defines the routing decisions based on one of the following routing options.
    Name Provide a name for the rule.
    Condition Operator Specifies the condition operator to be used.

    Select one of the following operators:

    • OR. Specifies that one of the set conditions should be applied.
    • AND. Specifies all the set conditions should be applied.
    Add Condition Specify the context variables for processing client requests.
    • Variable: Specifies the variable type.
    • Operator: Specifies the operator to use to relate variable and the value. You can select one of the following:
      • Equals
      • Equals ignore case
      • Not equals
      • Not equals ignore case
      • Contains
      • Not Contains
      • Exists
      • Not Exists
      • Range
      • Greater Than
      • Less Than
    • Value: Specifies a plain value or value with a syntax.

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

    Route To. Specifies the endpoint URI of 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. You can use service registries in a similar manner as described in the main Endpoint URI above.

    For example, if your service is hosted at the URL: http://hostname/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 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, 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 for 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.

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

    Specifies values to enable SSL authentication for SOAP APIs.

    Select one of the following options:

    • MTOM. API Gateway uses the Message Transmission Optimization Mechanism (MTOM) to parse SOAP requests to the API.
    • SwA. API Gateway uses the SOAP with Attachment (SwA) technique to parse SOAP requests to the API.
    • None. 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 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 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 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 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 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 API Gateway uses the default value of 30 seconds.
    Pass WS-Security Headers This is applicable for SOAP-based APIs.

    Selecting this indicates that 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.
    Provide the following information:
    • Keystore Alias. Specifies the keystore alias configured in 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 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: A value for the path parameter. 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 registry) and the corresponding values for the path parameter as ${request.header.var1}, the value in var1 retrieved from the request header substitutes the service name.

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

    Dynamic Routing

    This policy enables 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, Software AG 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:

    Parameter 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://hostname/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 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, 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: Software AG 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 API Gateway can use to parse SOAP requests to the native API.

    Select one of the following options:

    • MTOM. API Gateway uses the Message Transmission Optimization Mechanism (MTOM) to parse SOAP requests to the API.
    • SwA. API Gateway uses the SOAP with Attachment (SwA) technique to parse SOAP requests to the API.
    • None. 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 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 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 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 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 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 API Gateway uses the default value of 30 seconds.
    Pass WS-Security Headers This is applicable for SOAP-based APIs.

    Selecting this indicates that 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 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 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: A value for the path parameter. 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 registry) and the corresponding values for the path parameter as ${request.header.var1}, the value in var1 retrieved from the request header substitutes the service name.

    For details about the variables available in 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. API Gateway takes this ROUTING_ENDPOINT value as the native endpoint value and performs the routing.
    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.

      For example, if your service is hosted at the URL: http://hostname/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 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, 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 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 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 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 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 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 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 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 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 API Gateway can use to parse SOAP requests to the native API.

    Select one of the following options:

    • MTOM. API Gateway uses the Message Transmission Optimization Mechanism (MTOM) to parse SOAP requests to the API.
    • SwA. API Gateway uses the SOAP with Attachment (SwA) technique to parse SOAP requests to the API.
    • None. 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 API Gateway should pass the WS-Security headers of the incoming requests to the native API.

    Load Balancer Routing

    If you have an API that is hosted at two or more endpoints, you can use the load balancing option to distribute requests among the endpoints. Requests are distributed across multiple endpoints. The requests are routed based on the round-robin execution strategy. The load for a service is balanced by directing requests to two or more services in a pool, until the optimum level is achieved. The application routes requests to services in the pool sequentially, starting from the first to the last service without considering the individual performance of the services. After the requests have been forwarded to all the services in the pool, the first service is chosen for the next loop of forwarding.

    If the entry protocol is HTTP or HTTPS, you can select the Load Balancer routing.

    The table lists the properties that you can specify for this policy:

    Parameter 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://hostname/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 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, 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 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.

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

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

    Select one of the following options:

    • MTOM. API Gateway uses the Message Transmission Optimization Mechanism (MTOM) to parse SOAP requests to the API.
    • SwA. API Gateway uses the SOAP with Attachment (SwA) technique to parse SOAP requests to the API.
    • None. 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 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 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 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 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 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 API Gateway uses the default value of 30 seconds.
    Suspend duration (seconds) A numeric timeout value (in seconds). The default value is 30.

    This property specifies the time, in seconds, for which API Gateway temporarily suspends an endpoint, whenever Read time-out or Connection time-out occurs for the endpoint, and routes the request to the next configured endpoint in this time interval.

    For example: If you have 3 endpoints configured endpoint #1, endpoint #2, and endpoint #3, the suspend duration is configured as 60 seconds for endpoint #2, and there is a Read Timeout or Connection Timeout for endpoint #2, then API Gateway temporarily suspends endpoint #2 for 60 seconds. In this time interval API Gateway skips endpoint #2 while routing the requests to the configured endpoints.

    Request 1 -> endpoint #1

    Request 2 -> endpoint #3 (endpoint #2 is suspended for 60 seconds and hence the request is sent to endpoint #3

    Request 3 -> endpoint #1

    Pass WS-Security Headers This is applicable for SOAP-based APIs.

    Selecting this indicates that 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 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 above 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 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: A value for the path parameter. 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 registry) and the corresponding values for the path parameter as ${request.header.var1}, the value in var1 retrieved from the request header substitutes the service name.

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

    Straight Through Routing

    When you select the Straight Through routing protocol, the API routes the requests directly to the native service endpoint you specify. If your entry protocol is HTTP or HTTPS, you can select the Straight Through routing policy.

    The table lists the properties that you can specify for this policy:

    Parameter Value
    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://hostname/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 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, 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: Software AG 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 API Gateway can use to parse SOAP requests to the native API.

    Select one of the following options:

    • MTOM. API Gateway uses the Message Transmission Optimization Mechanism (MTOM) to parse SOAP requests to the API.
    • SwA. API Gateway uses the SOAP with Attachment (SwA) technique to parse SOAP requests to the API.
    • None. 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 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 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 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 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 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 API Gateway uses the default value of 30 seconds.
    Pass WS-Security Headers This is applicable for SOAP-based APIs.

    Selecting this indicates that 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 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 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: A value for the path parameter. 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 registry) and the corresponding values for the path parameter as ${request.header.var1}, the value in var1 retrieved from the request header substitutes the service name.

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

    Custom HTTP Header

    You can use this policy to route requests based on the custom HTTP headers specified for the outgoing message to the native service.

    The table lists the properties that you can specify for this policy:

    Parameter Description
    HTTP Header Key Specifies the HTTP header key contained in the requests.
    Header Value Specifies the Header value contained in the requests. As this property supports variable framework, you can use the available variables to specify the header value. For example, if you provide a header value as ${request.header.token1}, the header value in token1 is sent in the outgoing message to authenticate the backend services. For details about the variables available in API Gateway, see Variables available in API Gateway.

    You can add multiple entries for the Header key-value pair by clicking icon.

    Outbound Auth - Transport

    When the native API is protected and expects the authentication credentials to be passed through transport headers, you can use this policy to provide the credentials that will be added to the request and sent to the native API. API Gateway supports a wide range of authentication schemes, such as Basic Authentication, Kerberos, NTLM, and OAuth, at the transport-level.

    Note: Transport-level authentication can be used to secure inbound communication of both the SOAP APIs and the REST APIs.

    The table lists the properties that you can specify for this policy:

    Parameter Description
    Authentication scheme Select one of the following schemes for outbound authentication at the transport level:
    • Basic. Uses basic HTTP authentication details to authenticate the client.
    • Kerberos. Uses Kerberos credentials for authentication.
    • NTLM. Uses NTLM configuration for authentication.
    • OAuth2. Uses OAuth token details to authenticate the client.
    • JWT. Uses JSON web token details to authenticate the client.
    • Anonymous. Authenticates the client without any credentials.
    • Alias. Uses the configured alias name for authentication.
    Authenticate using Select one of the following modes to authenticate the client:
    • Custom credentials. Uses the values specified in the policy to obtain the required token to access the native API.
    • Delegate incoming credentials. Uses the values specified in the policy by the API providers to select whether to delegate the incoming token or act as a normal client.
    • Incoming HTTP Basic Auth credentials. Uses the incoming user credentials to retrieve the authentication token to access the native API.
    • Incoming kerberos credentials. Uses the incoming kerberos credentials to access the native API.
    • Incoming OAuth token. Uses the incoming OAuth2 token to access the native API.
    • Incoming JWT. Uses the incoming JSON Web Token (JWT) to access the native API.
    • Transparent. Enables NTLM handshake between client and native API. API Gateway does not perform any authentication before passing the incoming requests to native API. It simply passes the incoming credentials to native API. The NTLM authentication happens at the native API.
    Basic Uses the HTTP authentication details to authenticate the client. API Gateway supports the following modes of HTTP authentication:
    • Custom credentials
    • Incoming HTTP Basic Auth credentials
    Provide the following credentials
    • User Name. Specifies the user name.
    • Password. Specifies the password of the user.
    • Domain. Specifies the domain in which the user resides.
    Kerberos Uses the Kerberos credentials to authenticate the client. API Gateway supports the following modes of Kerberos authentication:
    • Custom credentials
    • Delegate incoming credentials
    • Incoming HTTP basic auth credentials
    • Incoming kerberos credentials

    • Provide the following credentials
    • Client principal. Provide a valid client LDAP user name.
    • Client password. Provide a valid password of the client LDAP user.
    • Service principal. Provide a valid SPN. The specified value is used by the client to obtain a service ticket from the KDC server.
    • Service Principal Name Form. The SPN type to use while authenticating an incoming client principal name. Select any of the following:
    • User name. Specifies the username form.
    • Hostbased. Specifies the host form.
    NTLM Uses the NTLM credentials to authenticate the client. API Gateway supports the following modes of NTLM authentication:
    • Custom credentials
    • Incoming HTTP basic auth credentials
    • Transparent

    • Provide the following credentials
    • User Name. Specifies the user name.
    • Password. Specifies the password of the user.
    • Domain. Specifies the domain in which the user resides.
    OAuth2 Uses the OAuth2 token to authenticate the client. API Gateway supports the following modes of NTLM authentication:
    • Custom credentials
    • Incoming OAuth token

    • OAuth2 token. Specifies the client’s OAuth2 token
    JWT Uses the JSON Web Token (JWT) to authenticate the client. If the native API is enforced to use JWT for authenticating the client, then API Gateway enforces the need for a valid JWT in the outbound request while accessing the native API.
    API Gateway supports the Incoming JWT mode of JWT authentication
    Alias Name of the configured alias.

    When you configure an API with an inbound authentication policy, and a client sends a request with credentials, API Gateway uses the credentials for the inbound authentication. When sending the request to native server, API Gateway removes the already authenticated credentials when no outbound authentication policy is configured.

    If as an API provider you want to use the same credentials for authentication at both API Gateway and native server, you should configure the outbound authentication policy to pass the incoming credentials to the native service. If you do not configure an outbound authentication policy, API Gateway removes the incoming credentials, as it is meant for API Gateway authentication only.

    However, when both the inbound authentication policy and outbound authentication policy are not configured, API Gateway just acts as a proxy and forwards the credentials to the native service. Since the credentials are not meant for API Gateway (as no inbound auth policy is configured), API Gateway forwards the credentials to native service (unless there are different settings configured in outbound authentication policy, for example, custom credentials or Anonymous).

    Outbound Auth - Message

    When the native API is protected and expects the authentication credentials to be passed through payload message, you can use this policy to provide the credentials that is added to the request and sent to the native API. API Gateway supports a wide range of authentication schemes, such as WSS Username, SAML, and Kerberos, in addition to signing and encryption at the message-level.

    Note: Message-level authentication can be used to secure outbound communication of only SOAP APIs.

    The table lists the properties that you can specify for this policy:

    Parameter Description
    Authentication scheme Select one of the following schemes for outbound authentication at the message level:
    • WSS username. Uses WSS credentials authenticate the client.
    • SAML. Uses SAML issuer configuration details for authentication.
    • Kerberos. Uses Kerberos credentials for authentication.
    • None. Authenticates the client without any authentication schemes.
    • Alias. Uses the configured alias name for authentication.
    • Remove WSS headers. Uses the WSS headers for authentication.
    Authenticate using Select one of the following modes to authenticate the client:
    • Custom credentials. Uses the values specified in the policy to obtain the required token to access the native service.
    • Incoming HTTP Basic Auth credentials. Uses the incoming user credentials to retrieve the authentication token to access the native API
    • Delegate incoming credentials. Uses the values specified in the policy by the API providers to select whether to delegate the incoming token or act as a normal client.
    WSS username Uses the WSS credentials to authenticate the client. Provide the following credentials:
    • User Name. Specifies the user name.
    • Password. Specifies the password of the user.
    Kerberos Uses the Kerberos credentials to authenticate the client. Provide the following information:
    • Client principal. Provide a valid client LDAP user name.
    • Client password. Provide a valid password of the client LDAP user.
    • Service principal. Provide a valid SPN. The specified value is used by the client to obtain a service ticket from the KDC server.
    • Service Principal Name Form. The SPN type to use while authenticating an incoming client principal name. Select any of the following:
    • User name. Specifies the username form.
    • Hostbased. Specifies the host form.
    SAML Provide the SAML issuer that is configured.
    Signing and Encryption Configurations Uses the signing and encryption configuration details to authenticate the client. Provide the following information:
    • Keystore Alias. Specifies a user-specified text identifier for an API Gateway keystore. The alias points to a repository of private keys and their associated certificates.
    • 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. The truststore contains the trusted root certificate for the CA that signed the API Gateway certificate associated with the key alias.
    • Certificate alias. Provide a text identifier for the certificate associated with the truststore alias. API Gateway populates the certificate alias list with the certificate aliases from the selected truststore alias.
    Alias Uses the Kerberos credentials to authenticate the client. Provide the name of the configured alias.

    When you configure an API with an inbound authentication policy, and a client sends a request with credentials, API Gateway uses the credentials for the inbound authentication. When sending the request to native server, API Gateway removes the already authenticated credentials when no outbound authentication policy is configured.

    If as an API provider you want to use the same credentials for authentication at both API Gateway and native server, you should configure the outbound authentication policy to pass the incoming credentials to the native service. If you do not configure an outbound authentication policy, API Gateway removes the incoming credentials, as it is meant for API Gateway authentication only.

    However, when both the inbound authentication policy and outbound authentication policy are not configured, API Gateway just acts as a proxy and forwards the credentials to the native service. Since the credentials are not meant for API Gateway (as no inbound auth policy is configured), API Gateway forwards the credentials to native service (unless there are different settings configured in outbound authentication policy, for example, custom credentials or Anonymous).

    Traffic Monitoring

    The policies in this stage provide ways to enable logging request and response payload, enable monitoring run-time performance conditions for APIs and applications, enforce limits for the number of service invocations during a specified time interval and send alerts to a specified destination when the performance conditions are violated, and enable caching of the results of API invocations depending on the caching criteria defined. The policies included in this stage are:

    Log Invocation

    This policy enables logging requests or responses to a specified destination. This action also logs other information about the requests or responses, such as the API name, operation name, the Integration Server user, a timestamp, and the response time.

    The table lists the properties that you can specify for this policy:

    Parameter Description
    Store Request Headers Logs all request headers.
    Store Request Payload Logs all request payloads.
    Store Response Headers Logs all response headers.
    Store Response Payload Logs all response payloads.
    Compress Payload Data Compresses the logged payload data.
    Log Generation Frequency Specifies how frequently to log the payload. Select one of the following options:
    • Always. Logs all requests and responses.
    • On Failure. Logs only the failed requests and responses.
    • On Success. Logs only the successful responses and requests.
    Destination Specifies the destination where to log the payload. Select the required options:
    • API Gateway
    • API Portal
    • CentraSite
    Note: This option is applicable only for the APIs published from CentraSite to API Gateway.
    • Elasticsearch
    • Email (you can add multiple email addresses by clicking ).
    Note: If an email alias is available, you can type the email alias in the Email Address field with the following syntax, ${emailaliasname}. For example, if test is the email alias, then type ${test}.

    Monitor Performance

    This policy is similar to the Monitor SLA policy and does monitor the same set of run-time performance conditions for an API, and sends alerts when the performance conditions are violated. However, this policy monitors run-time performance at the API level. Parameters like success count, fault count and total request count are immediate monitoring parameters and the evaluation happens immediately after the limit is breached. The rest of the parameters are Aggregated monitoring parameters whose evaluation happens once the configured interval is over. If there is a breach in any of the parameters, an event notification ( Monitor event) is sent to the configured destination. In a single policy, multiple action configurations behave as AND condition. The OR condition can be achieved by configuring multiple policies.

    The table lists the properties that you can specify for this policy:

    Parameter Value
    Action Configuration. Specifies the type of action to be configured.
    Name Specifies the name of the metric to be monitored.

    You can select one of the available metrics:

    • Availability. Indicates whether the native API is available to the clients as specified in the current interval. API Gateway calculates the availability of the native API based on the alert interval specified and it is calculated from the instant the API activation takes place.

      The availability of the API is calculated as = (time for which the native API is up / total interval of time) x 100. This value is measured in %.

      For example, if you set Availability as less than 90, then whenever the availability of the native API falls below 90%, in the specified time interval, API Gateway generates an alert. Suppose, the alert interval is set as 1 minute (60 seconds) and if there are 7 API invocations at various times in that 1 minute with a combination of up and down as shown in the table, the availability is calculated as follows:

      Request# Invocation time Service status Up time
      1 5 Up 5 (from start to now)
      2 15 Up 10 (between 1 and 2)
      3 30 Down 15 (between 2 and 3)
      4 40 Down 0 (since last state is down)
      5 45 Up 0
      6 50 Down 5 (between 5 and 6)
      7 55 Up 0
      5 (remaining 5 seconds considered as Up inline with last state)
      Total 40 (Availability is 67%)

      As the availability of the native API calculated is 66.67% and falls below 90%, API Gateway generates an alert. The API is considered to be down for the ongoing request when API Gateway receives a connection related error from the native API in the outbound call. If the API does not respond with an HTTP response, then it is considered as down.

    • Average Response Time. Indicates the average time taken in milliseconds (ms) by the service to complete all invocations in the current interval. The average is calculated from the instant the API activation takes place for the configured interval.

      For example, if you set an alert for Average response time greater than 30 ms with an interval of 1 minute then on API activation, the monitoring interval starts and the average of the response time of all runtime invocations for this API in 1 minute is calculated. If this is greater than 30 ms, then a monitor event is generated. If this is configured under Monitor service performance, then all the runtime invokes are taken into account.

    • Fault Count. Indicates the number of faults returned in the current interval.
    • Maximum Response Time. Indicates the maximum time in milliseconds (ms) to respond to a request in the current interval.
    • Minimum Response Time. Indicates the minimum time in milliseconds (ms) to respond to a request in the current interval.
    • Success Count. Indicates the number of successful requests in the current interval.
    • Total Request Count. Indicates the total number of requests (successful and unsuccessful) in the current interval.
    Operator Specifies the operator applicable to the metric selected.

    Select one of the available operator: Greater Than, Less Than, Equals To.

    Value Specifies the alert value for which the monitoring is applied.
    Destination Specifies the destination where the alert is to be logged.

    Select the required options:

    • API Gateway
    • API Portal
    • CentraSite

      Note: This option is applicable only for the APIs published from CentraSite to API Gateway.
    • Elasticsearch
    • Email (you can add multiple email addresses by clicking icon).
      Note: If an email alias is available, you can type the email alias in the Email Address field with the following syntax, ${emailaliasname}. For example, if test is the email alias, then type ${test}.
    • Local Log: You can select the severity of the messages to be logged (logging level) from the Log Level drop-down list. The available log levels are ERROR, INFO, and WARN.
    • For details on publishing to custom destinations, see How Do I Publish API-specific Traffic Monitoring Data to a Custom Destination.
    Alert Interval Specifies the time period in which to monitor performance before sending an alert if a condition is violated.

    The timer starts once the API is activated and resets after the configured time interval. If and API is deactivated the interval gets reset and on API activation its starts afresh.

    Unit Specifies the unit of measurement of the Alert Interval configured, to monitor performance, before sending an alert. For example:
    • Minutes
    • Hours
    • Days
    • Calendar Week.The time interval starts on the first day of the week and ends on the last day of the week. By default, the start day of the week is set to Monday.

      For example:

      • If an API is activated on a Wednesday and Alert Interval is set to 1, the time interval ends on Sunday, that is, 5 days.
      • If an API is activated on a Wednesday and Alert Interval is set to 2, the time interval ends on Sunday, but the period is two calendar weeks, that is 12 days.

      You can change the start day of the week using the extended setting startDayOfTheWeek in the Administration > General > Extended settings section. This extended setting needs a restart of the API Gateway server for the changes to take effect. Please contact Software AG Support team to restart the API Gateway server.

    • Calendar Month. The time interval starts on the first day of the month and ends on the last day of the month.

      For example:

      • If an API is activated on a Wednesday and Alert Interval is set to 1, the time interval ends on the last day of August.
      • If an API is activated on a Wednesday and Alert Interval is set to 2, the time interval ends in two calendar months, that is on the last day of September.
    Alert Frequency Specifies how frequently to issue alerts for the counter-based metrics (Total Request Count, Success Count, Fault Count).

    Select one of the options:

    • Only Once. Triggers an alert only the first time one of the specified conditions is violated.
    • Every Time. Triggers an alert every time one of the specified conditions is violated.
    Alert Message Specifies the text to be included in the alert.

    Monitor SLA

    This policy monitors a set of run-time performance conditions for an API, and sends alerts to a specified destination when the performance conditions are violated. This policy enables you to monitor run-time performance for one or more specified applications. You can configure this policy to define a Service Level Agreement (SLA), which is a set of conditions that defines the level of performance that an application should expect from an API. You can use this policy to identify whether the API threshold rules are met or exceeded. For example, you might define an agreement with a particular application that sends an alert to the application if responses are not sent within a certain maximum response time. You can configure SLAs for each API or application combination.

    Parameters like success count, fault count and total request count are immediate monitoring parameters and the evaluation happens immediately after the limit is breached. The rest of the parameters are Aggregated monitoring parameters whose evaluation happens once the configured interval is over. If there is a breach in any of the parameters, an event notification ( Monitor event) is sent to the configured destination. In a single policy, multiple action configurations behave as AND condition. The OR condition can be achieved by configuring multiple policies.

    The table lists the properties that you can specify for this policy:

    Parameter Value
    Action Configuration. Specifies the type of action to be configured.
    Name Specifies the name of the metric to be monitored.

    You can select one of the available metrics:

    • Availability. Indicates whether the native API is available to the clients as specified in the current interval. API Gateway calculates the availability of the native API based on the alert interval specified and it is calculated from the instant the API activation takes place.

      The availability of the API is calculated as = (time for which the native API is up / total interval of time) x 100. This value is measured in %.

      For example, if you set Availability as less than 90, then whenever the availability of the native API falls below 90%, in the specified time interval, API Gateway generates an alert. Suppose, the alert interval is set as 1 minute (60 seconds) and if there are 7 API invocations at various times in that 1 minute with a combination of up and down as shown in the table, the availability is calculated as follows:

      Request# Invocation time Service status Up time
      1 5 Up 5 (from start to now)
      2 15 Up 10 (between 1 and 2)
      3 30 Down 15 (between 2 and 3)
      4 40 Down 0 (since last state is down)
      5 45 Up 0
      6 50 Down 5 (between 5 and 6)
      7 55 Up 0
      5 (remaining 5 seconds considered as Up inline with last state)
      Total 40 (Availability is 67%)

      As the availability of the native API calculated is 66.67% and falls below 90%, API Gateway generates an alert. The API is considered to be down for the ongoing request when API Gateway receives a connection related error from the native API in the outbound call. If the API does not respond with an HTTP response, then it is considered as down.

    • Average Response Time. Indicates the average time taken by the service to complete all invocations in the current interval. The average is calculated from the instant the API activation takes place for the configured interval.

      For example, if you set an alert for Average response time greater than 30 ms with an interval of 1 minute then on API activation, the monitoring interval starts and the average of the response time of all runtime invocations for this API in 1 minute is calculated. If this is greater than 30 ms, then a monitor event is generated. If this is configured under Monitor SLA policy with an option to configure applications so that application specific SLA monitoring can be done, then the monitoring for the average response time is done only for the specified application.

    • Fault Count. Indicates the number of faults returned in the current interval.The HTTP status codes greater than or equal to 400, returned from API Gateway are considered as fault request transactions. This includes the downtime errors as well.
    • Maximum Response Time. Indicates the maximum time to respond to a request in the current interval.
    • Minimum Response Time. Indicates the minimum time to respond to a request in the current interval.
    • Success Count. Indicates the number of successful requests in the current interval.
    • Total Request Count. Indicates the total number of requests (successful and unsuccessful) in the current interval.
    Operator Specifies the operator applicable to the metric selected.

    Select one of the available operator: Greater Than, Less Than, Equals To.

    Value Specifies the alert value for which the monitoring is applied.
    Destination Specifies the destination where the alert is to be logged.

    Select the required options:

    • API Gateway
    • API Portal
    • CentraSite

      Note: This option is applicable only for the APIs published from CentraSite to API Gateway.
    • Elasticsearch
    • Email (you can add multiple email addresses by clicking icon).
      Note: If an email alias is available, you can type the email alias in the Email Address field with the following syntax, ${emailaliasname}. For example, if test is the email alias, then type ${test}.
    • Local Log: You can select the severity of the messages to be logged (logging level) from the Log Level drop-down list. The available log levels are ERROR, INFO, and WARN.
    • For details on publishing to custom destinations, see How Do I Publish API-specific Traffic Monitoring Data to a Custom Destination.
    Alert Interval Specifies the time period in which to monitor performance before sending an alert if a condition is violated.

    The timer starts once the API is activated and resets after the configured time interval. If and API is deactivated the interval gets reset and on API activation its starts afresh.

    Unit Specifies the unit of measurement of the Alert Interval configured, to monitor performance, before sending an alert. For example:
    • Minutes
    • Hours
    • Days
    • Calendar Week.The time interval starts on the first day of the week and ends on the last day of the week. By default, the start day of the week is set to Monday.

      For example:

      • If an API is activated on a Wednesday and Alert Interval is set to 1, the time interval ends on Sunday, that is, 5 days.
      • If an API is activated on a Wednesday and Alert Interval is set to 2, the time interval ends on Sunday, but the period is two calendar weeks, that is 12 days.

      You can change the start day of the week using the extended setting startDayOfTheWeek in the Administration > General > Extended settings section. This extended setting needs a restart of the API Gateway server for the changes to take effect. Please contact Software AG Support team to restart the API Gateway server.

    • Calendar Month. The time interval starts on the first day of the month and ends on the last day of the month.

      For example:

      • If an API is activated on a Wednesday and Alert Interval is set to 1, the time interval ends on the last day of August.
      • If an API is activated on a Wednesday and Alert Interval is set to 2, the time interval ends in two calendar months, that is on the last day of September.
    Alert Frequency Specifies how frequently to issue alerts for the counter-based metrics (Total Request Count, Success Count, Fault Count).

    Select one of the options:

    • Only Once. Triggers an alert only the first time one of the specified conditions is violated.
    • Every Time. Triggers an alert every time one of the specified conditions is violated.
    Alert Message Specifies the text to be included in the alert.
    Consumer Applications Specifies the application to which this Service Level Agreement applies.

    You can type a search term to match an application and click icon to add it.

    You can add multiple applications or delete an added application by clicking icon.

    Traffic Optimization

    This policy limits the number of service invocations during a specified time interval, and sends alerts to a specified destination when the performance conditions are violated. You can use this action to avoid overloading the back-end services and their infrastructure, to limit specific clients in terms of resource usage, and so on.

    The table lists the properties that you can specify for this policy:

    Parameter Description
    Limit Configuration
    Rule name Specifies the name of throttling rule to be applied. For example, Total Request Count.
    Operator Specifies the operator that connects the rule to the value specified.

    Select one of the operators: Greater Than, Less Than, Equals To.

    Value Specifies the value of the request count beyond which the policy is violated.

    When multiple requests are made at the same time, it might be possible that this limit applied to trigger an alert is not strictly adhered to. There is no loss observed in the invocation counts data, but there might be a minor delay in aggregating the count. The invocation count gets incremented, only when API Gateway receives the response from the native API. For example, if you have set the limit at 5 with an interval alert of 1 minute and if you invoke 5 requests in parallel, out of which for 1 of the request the native API delays sending the response to API Gateway. In such cases, the invocation count would still be 4 as the native API is yet to send the response to API Gateway. There is a minor delay in aggregating the count due to native API response delay. Hence, API Gateway allows additional invocation. However, when the invocation count exceeds 5 an alert is triggered.

    Destination Specifies the destination to log the alerts.

    Select the required options:

    • API Gateway
    • API Portal
    • CentraSite

      Note: This option is applicable only for the APIs published from CentraSite to API Gateway.
    • Elasticsearch
    • Email (you can add multiple email addresses by clicking icon).
      Note: If an email alias is available, you can type the email alias in the Email Address field with the following syntax, ${emailaliasname}. For example, if test is the email alias, then type ${test}.
    • Local Log: You can select the severity of the messages to be logged (logging level) from the Log Level drop-down list. The available log levels are ERROR, INFO, and WARN.
    • For details on publishing to custom destinations, see How Do I Publish API-specific Traffic Monitoring Data to a Custom Destination.
    Alert Interval Specifies the interval of time for the limit to be reached.
    Unit Specifies the unit of measurement of the Alert Interval configured, to monitor performance, before sending an alert. For example:
    • Minutes
    • Hours
    • Days
    • Calendar Week.The time interval starts on the first day of the week and ends on the last day of the week. By default, the start day of the week is set to Monday.

      For example:

      • If an API is activated on a Wednesday and Alert Interval is set to 1, the time interval ends on Sunday, that is, 5 days.
      • If an API is activated on a Wednesday and Alert Interval is set to 2, the time interval ends on Sunday, but the period is two calendar weeks, that is 12 days.

      You can change the start day of the week using the extended setting startDayOfTheWeek in the Administration > General > Extended settings section. This extended setting needs a restart of the API Gateway server for the changes to take effect. Please contact Software AG Support team to restart the API Gateway server.

    • Calendar Month. The time interval starts on the first day of the month and ends on the last day of the month.

      For example:

      • If an API is activated on a Wednesday and Alert Interval is set to 1, the time interval ends on the last day of August.
      • If an API is activated on a Wednesday and Alert Interval is set to 2, the time interval ends in two calendar months, that is on the last day of September.
    Alert Frequency Specifies the frequency at which the alerts are issued.
    Specify one of the options:
    • Only Once. Triggers an alert only the first time the specified condition is violated.
    • Every Time. Triggers an alert every time the specified condition is violated.
    Alert Message Specifies the text message to be included in the alert.
    Consumer Applications Specifies the application to which this policy applies.

    You can type a search term to match an application and click icon to add it.

    You can add multiple applications or delete an added application by clicking icon.

    Service Result Cache

    This policy enables caching of the results of API invocations depending on the caching criteria defined. You can define the elements for which the API responses are to be cached based on the criteria such as HTTP Header, XPath, Query parameters, and so on. You can also limit the values to store in the cache using a whitelist. For the elements that are stored in the cache, you can specify other parameters such as Time to Live and Maximum Response Payload Size.

    Caching the results of an API request increases the throughput of the API call and improves the scalability of the API.

    The cache criteria applicable for a SOAP-based API request are HTTP Header and XPATH. The cache criteria applicable for a REST-based API request are HTTP Header and Query parameters. The caching works only for GET methods for REST APIs.

    Note: If there are no values set for any of the criteria, then, by default, all the SOAP requests and GET requests for the Rest API are based on the URL.

    The table lists the properties that you can specify for this policy:

    Parameter Description
    Cache Criteria Specifies the criteria that API Gateway uses to determine the request component, that is, the actual payload based on which the results of the API invocation are cached.
    HTTP Header Uses the HTTP header in the API request. You can use this criterion for APIs that accept payloads only in HTTP format.

    Header Name. Specifies the HTTP header name.

    Cache responses only for these values. API Gateway caches the API responses only for requests whose cache criteria match with those set for the action, and whose criteria evaluation results in any one of the values in this list. You can add multiple entries by clicking icon.
    Note: If this field is empty, all the values that satisfy the criterion are cached.
    Query Parameters You can use this criterion for REST-based API requests. Specifies the names and values of the query parameters to filter the incoming requests and cache the results based on the names and values specified.

    Parameter Name. Specifies the parameter name.

    Cache responses only for these values. API Gateway caches the API responses only for requests whose cache criteria match those set for the action, and whose criteria evaluation results in any one of the values in this list. You can add multiple entries by clicking icon.

    XPath You can use this criterion for SOAP-based API requests whose payload is a SOAP envelope. Uses the XPath expression in the API request.
    • Name Space. Specifies the namespace of the XPath expression.
      • Prefix. Specifies the prefix for the namespace.
      • URI. Specifies the namespace URI.

      You can add multiple entries by clicking icon.

    XPath Expression. Specifies the XPath expression in the API request.

    Cache responses only for these values. API Gateway caches the API responses only for requests whose cache criteria match those set for the action, and whose criteria evaluation results in any one of the values in this list. You can add multiple entries by clicking icon.
    Note: If this field is empty, all the values that satisfy the criteria are cached.
    Time to Live (e.g., 5d 4h 1m) Specifies the lifespan of the elements in the cache after which the elements are considered to be out-of-date.

    The time is specified in terms of days, hours, and minutes; for example, 5d 4h 1m.

    If you do not specify any value, the Time to Live is considered to be unlimited (does not expire). If you set the value to 0d 0h 0m, the API results are not cached.

    The default time format is minutes if the input is a number.

    Maximum Response Payload Size (in KB) Specifies the maximum payload size for the API in kilo bytes.

    The value -1 stands for unlimited payload size.

    Example of enforcing caching criteria:

    Cache criteria HTTP Header Query parameters XPATH Values
    C1 Header1     h1, h2
    C2 Header2      
    C3   query1   q1, q2

    In the example, there are two HTTP headers and one query parameter as cache criteria. The HTTP Header Header2 has no values specified. Hence, all the incoming requests with the HTTP Header Header2 are cached.
    When there are multiple cache criteria, the following behaviour is observed in the cache result:

    Response Processing

    These policies are used to specify how the response message from the API has to be transformed or pre-processed and configure the masking criteria for the data to be masked before it is submitted to the application. This is required to protect the data and accommodate differences between the message content that an API is capable of submitting and the message content that an application expects. The policies included in this stage are:

    Invoke webMethods IS

    This policy processes the native API’s response messages into the format required by the application, before API Gateway returns the responses to the application.

    If Comply to IS Spec parameter is configured as true, API Gateway invokes the IS Service with IS specification in the path pub.apigateway.invokeISService.specifications:ResponseSpec (for Response Processing)

    The following are the input and output parameters for REST and SOAP APIs as specified in the above IS Specification.

    API type Input parameters Output parameters
    REST
  • headers
  • payload
  • messageContext
  • statusCode
  • statusMessage
  • apiName
  • requestUrl
  • correlationID (this is unique for request and response)
  • headers
  • payload
  • messageContext
  • statusCode
  • statusMessage
  • SOAP
  • headers
  • payload
  • messageContext
  • statusCode
  • statusMessage
  • apiName
  • payloadObject
  • requestUrl
  • correlationID (this is unique for request and response)
  • headers
  • payload
  • messageContext
  • statusCode
  • statusMessage
  • Note:

    • For SOAP to REST APIS, the payload contains the transformed JSON response.
    • Payload transformation does not happen automatically for content-type transformation. When you change the content type, ensure to do payload transformation also as part of IS Service.
    • When Comply to IS Spec is true, you can change the values of headers, query, payload, and so on, programatically using Message Context, as well as using the pipeline variables given. Software AG recommends you do not change those values directly in Message Context, as the values in output pipeline variables are written to Message Context after the invocation of IS Service.

    If Comply to IS Spec parameter is set to false, API Gateway invokes the IS Service with the same input and output parameters supported in 10.1 and the earlier versions::

    The table lists the properties that you can specify for this policy:

    Parameter Description
    Invoke webMethods Integration Server Service
    Add invoke webMethods Integration Server service Specifies the webMethods IS service to be invoked to process the response messages and the authentication mode for the IS service.

    Provide the following information:

    • webMethods IS Service. Specify the webMethods IS service to be invoked to pre-process the response messages.
      The webMethods IS service must be running on the same Integration Server as API Gateway.
      Note: If an exception occurs when invoking the webMethods IS service, by default API Gateway displays the status code as 500 and error message as Internal Server Error.
      You can set custom status code and error message by setting the following properties in the message context of the webMethods IS service:
      • service.exception.status.code
      • service.exception.status.message
      The sample code is given below:
      IDataCursor idc = pipeline.getCursor();MessageContext context = (MessageContext)IDataUtil.get(idc,"MessageContext");if(context != null){context.setProperty"service.exception.status.code", 404);context.setProperty("service.exception.status.message", "Object Not Found");throw new ServiceException(); }
    • .
    • Comply to IS Spec. Mark this as true if you want the input and the output parameters to comply to the IS Spec present in pub.apigateway.invokeISService.specifications folder in wmAPIGateway package.
      Note: Software AG recommends users to configure the policy with Comply to IS Spec as true, as you can read or change the values of headers, and so on, without having to read from or write to the message context.
    webMethods IS Service alias Specifies the webMethods IS service alias used to invoke the webMethods IS service to pre-process the response messages.

    Start typing the webMethods alias name, select the alias from the type-ahead search results displayed and click icon to add one or more aliases.

    You can use the delete icon icon to delete the added aliases from the list.

    Response Transformation

    This policy specifies the properties required to transform response messages from native APIs into a format required by the client.

    This policy enables you to configure several transformations on the response messages before it is sent to the client.

    The table lists the properties that you can specify for this policy:

    Parameter Description
    Condition Conditions are used to specify when the policy has to be executed. We can add multiple conditions with logical operators.
    Available values are:
    • AND. API Gateway transforms the responses that comply with all the configured conditions
    • OR. This is selected by default. API Gateway transforms the responses that comply at least one configured condition.
    Click Add Condition and provide the following information and click icon.
    • Variable. Specifies the variable type with a syntax.
    • Variable: Specifies the variable type with a syntax.
    • Operator: Specifies the operator to use to relate variable and the value provided. You can select one of the following:
      • Equals
      • Equals ignore case
      • Not equals
      • Not equals ignore case
      • Contains
      • Not Contains
      • Exists
      • Not Exists
      • Range
      • Greater Than
      • Less Than
    • Value: Specifies a plain value or value with a syntax.

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

    Transformation Configuration. Specifies various transformations to be configured.
    Header Transformation Specifies the Header, Query or path transformation to be configured for the responses received from the native API.

    You can add or modify header, query or path transformation parameters by providing the following information:

    • Variable. Specifies the variable type with a syntax.
    • Value: Specifies a plain value or value with a syntax.

    You can add multiple variables and corresponding values by clicking icon.

    You can remove any header, query, or path transformation parameters by typing the plain value or value with a syntax.

    Note: Software AG recommends you not to modify the headers ${response.headers.Content-Length} and ${response.headers.Content-Encoding} as API Gateway adds the right values for these headers before sending the response back to client.

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

    Note: Payload transformation does not happen automatically for content-type transformation. When you change the content type, ensure to do payload transformation. For example, if you change the content-type header from application/xml to application/json, you must also change the respective payload from application/xml to application/json.
    Status transformation Specifies the status transformation to be configured for the responses received from the native API.

    Provide the following information:

    • Code. Specifies the status code that is sent in the response to the client.

      For example if you want to transform status code as 201, provide 201 in the Code field.

    • Message. Specifies the Status message that is sent in the response to the client.

      As both these properties support variable framework, you can make use of the available variables to transform the response code and message.

      For example, You have submitted successfully

    • can be used to transform the original OK status message.

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

    Payload Transformation Specifies the payload transformation to be configured for the responses received from the native API.
    Provide the following information:
    • Payload Type. Specifies the content-type of payload, to which you want to transform. The Payload field renders the respective payload editor based on the selected content-type.
    • Payload. Specifies the payload transformation that needs to be applied for the response.
    • As this property supports variable framework, you can make use of the available variables to transform the response messages.

      For example, consider the client accepting two integer values value1 and value2, and you want to pass these two values from API Gateway to the client, you can configure the payload field as follows:

      {"value1" : 12,"value2" : 34}

      You can also configure the payload field using one or more variables by using variable framework. Let us see another syntax. For example, for the same native API seen in the previous example, if your native sends both the values through headers val1 and val2, and you want to add it to payload for the client to recognize the input, you can do so by configuring the payload field as follows:

      {"value1" :${request.headers.val1},"value2" :${request.headers.val2}}
      For details about the variables available in API Gateway, see Variables available in API Gateway.
      Note: If your payload content-type is different from the incoming payload's content-type, you need to transform the content-type of the header using Header Transformation.
    • Click + Add xslt document to add an xslt document and provide the following information:
      • XSLT file. Specifies the XSLT file used to transform the request messages as required.

        Click Browse to browse and select a file.

      • Feature Name. Specifies the name of the XSLT feature.
      • Feature value. Specifies the value of the XSLT feature.

        You can add more XSLT features and xslt documents by clicking icon.

      Note:API Gateway supports XSLT 1.0 and XSLT 2.0.
    • Click + Add xslt transformation alias and provide the following information:
      • XSLT Transformation alias. Specifies the XSLT transformation alias

        When the incoming request is in JSON, you can use a XSLT file similar to the below sample:

        
        <?xml version="1.0" ?>
        <xsl:stylesheet version="1.1"
        xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
        <xsl:output method="xml"/>
        <xsl:template match="/" >
        <xsl:element name="fakeroot">
        <xsl:element name="fakenode">
        <!-- Apply your transformation rules based on the response
        received from the native API>
        </xsl:element>
        </xsl:element>
        </xsl:template>
        </xsl:stylesheet>

        When you receive the response in XML, you can use a XSLT file similar to the below sample:

        
        <?xml version="1.0" ?>
        <xsl:stylesheet version="1.1"
        xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
        xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
        <xsl:output method="xml"/>
        <xsl:template match="/">
        <xsl:element name="soapenv:Envelope">
        <xsl:element name="soapenv:Body">
        <!-- Apply your transformation rules
        based on the response received from the native API>
        </xsl:element>
        </xsl:element>
        </xsl:template>
        </xsl:stylesheet>
    Advanced Transformation Specifies the advanced transformation to be configured for the responses received from the native API..
    Provide the following information:
    • webMethods IS Service. Specify the webMethods IS service to be invoked to process the response messages. The list displays only the pre-shipped Integration Server services, which you can invoke to pre-process or post-process the request or response message.

      You can add multiple services by clicking icon.

    • Comply to IS Spec. Mark this as true if you want the input and the output parameters to comply to the IS Spec present in pub.apigateway.invokeISService.specifications folder in wmAPIGateway package.
    • webMethods IS Service alias. Specifies the webMethods IS service alias to be invoked to pre-process the request messages.
    Transformation Metadata. Specifies the metadata for transformation of the responses received from the native API. For example, the namespaces configured in this section can be used when you provide the syntax for XPath ${response.payload.xpath} For example: ${response.payload.xpath[//ns:emp/ns:empName]}
    Namespace Specifies the namespace information to be configured for transformation.
    Provide the following information:
    • Namespace Prefix. The namespace prefix of the payload expression to be validated.

      For example, specify the namespace prefix as SOAP_ENV.

    • Namespace URI. The namespace URI of the payload expression to be validated.

      For example, specify the namespace URI as http://schemas.xmlsoap.org/soap/envelope/. This declaration defines SOAP_ENV as an alias for the namespace: http://schemas.xmlsoap.org/soap/envelope/.

      Note: You can add multiple namespace prefix and URI by clicking icon.

    Validate API Specification

    This policy validates the responses against API’s various specifications such as schema, content-types, and HTTP Headers referenced in their corresponding formats as follows:

    The response sent to the API by an application must conform with the structure or format expected by the API. The responses from the native API are validated against the API specifications in this policy to conform to the structure or format expected by the API.

    Various API specifications validated are:

    Content-type/Accept Schema validation type
    application/json
    application/json/badgerfish
    JSON schema
    application/xml
    text/xml
    text/htm
    XML schema
    text/plain Regex schema

    For a SOAP API, the WSDL and the referenced schema must be provided in a zip format. The JSON schema validation is supported for the operations that are exposed as REST.

    The run-time invocations that fail the specification validation are considered as policy violations. Such policy violation events that are generated can be viewed in the dashboard.

    The table lists the API specification properties, you can specify for this policy, to be validated:

    Parameter Description
    Schema Validates the request payload against the appropriate schema (based on the Content-type header in request or Accept header in response).
    Provide the following additional features for XML schema validation:
    • Feature name. Specifies the name of the feature for XML parsing when performing XML schema validation.

    • Select the required feature names from the list:
      • GENERATE_SYNTHETIC_ANNOTATIONS
      • ID_IDREF_CHECKING
      • IDENTITY_CONSTRAINT_CHECKING
      • IGNORE_XSL_TYPE
      • NAMESPACE_GROWTH
      • NORMALIZE_DATA
      • ROOT_ELEMENT_DECL
      • ROOT_TYPE_DEF
      • SIGMA_AUGMENT_PSVI
      • SCHEMA_DV_FACTORY
      • SCHEMA_ELEMENT_DEFAULT
      • SCHEMA_LOCATION
      • SCHEMA_NONS_LOCATION
      • SCHEMA_VALIDATOR
      • TOLERATE_DUPLICATES
      • ENPARSED_ENTITY_CHECKING
      • VALIDATE_ANNOTATIONS
      • XML_SCHEMA_FULL_CHECKING
      • XMLSCHEMA_VALIDATION

      For details about XML parsing features, see http://xerces.apache.org/xerces2-j/features.html and for details about the exact constants, see https://xerces.apache.org/xerces2-j/javadocs/xerces2/org/apache/xerces/parsers/XML11Configuration.html.
    • Feature value. Specifies whether the feature value is True or False.
    Query Parameters This is applicable only for a REST API. Validates the query parameters in the incoming request against the query parameters defined in that request’s API Specification. The configuration is provided in the API details page.
    Path Parameters This is applicable only for a REST API. Validates the path parameters in the incoming request against the path parameters defined in that request’s API Specification. The configuration is provided in the API details page.
    Content-types Validates the content-types in the incoming request against the content-types defined in that request’s API Specification. The configuration is provided in the API details page.
    HTTP Headers Validates the HTTP header parameters in the incoming request against the HTTP headers defined in that request’s API Specification. The configuration is provided in the API details page. Provide the following information:
    • Condition. Specifies the logical operator to use to validate multiple HTTP headers in the incoming API requests.

    • Available values are:
    • AND. API Gateway accepts only the requests that contain all configured HTTP headers.
    • OR. This is selected by default. API Gateway accepts requests that contain at least one configured HTTP header.
    • HTTP Header Key. Specifies a key that must be passed through the HTTP header of the incoming API requests.
    • Header Value. Optional. Specifies the corresponding key value that could be passed through the HTTP header of the incoming API responses. As this property supports variable framework, you can make use of the available variables to specify the header value.
    • For details about the variables available in API Gateway, see Variables available in API Gateway.
      You can add more HTTP headers by clicking icon

    CORS

    The Cross-Origin Resource Sharing (CORS) mechanism supports secure cross-domain requests and data transfers between browsers and web servers. The CORS standard works by adding new HTTP headers that allow servers to describe the set of origins that are permitted to read that information.

    This policy provides CORS support that uses additional HTTP headers to let a client or an application gain permission to access selected resources. An application or a client makes a cross-origin HTTP request when it requests a resource from a different domain, protocol, or port than the one from which the current request originated.

    If you want to apply this policy in API Gateway at API level, make sure you have set the watt.server.cors.enabled property to false.

    Note: Both the Integration Server CORS policy and API Gateway CORS policy cannot coexist. When you enforce the CORS policy at Integration Server level, CORS enforcement is done for all requests. The preflight requests are handled by the Integration Server before even it reaches API Gateway.

    This policy is applicable for REST, SOAP, and ODATA APIs.

    The table lists the CORS response specifications, you can specify for this policy:

    Parameter Description
    Allowed Origins Specifies the origin from which the responses originating are allowed. syntax for the origin: scheme://hostname
    You can add multiple origins by clicking icon
    You can also provide Regular expressions for allowed origins
    Allowed origins can also be specified in the Advanced section under Applications. Allowed origins of applications registered with this API are also allowed to access this API
    Allow Headers Specifies the Headers that are allowed in the request. You can add multiple headers that are to be allowed by clicking icon.
    Expose Headers Specifies the headers that be exposed to the user on request failure. You can add multiple headers that are to be allowed by clicking icon.
    Allow Credentials Specifies whether API Gateway includes the Access-Control-Allow-Credentials header.
    Allowed Methods Specifies the methods that are allowed in the request. Specify one or more of the following: GET, POST, PUT, DELETE, and PATCH.
    Max Age Specifies the age for which the preflight response is valid.

    A corresponding HTTP header is set for all the values above as per the specification. For additional information, see https://www.w3.org/TR/cors/.

    API Gateway handles CORS preflight request and CORS request differently. To know more about the work flow of CORS preflight and CORS request refer the respective flowchart.

    CORS Preflight Request

    A CORS preflight request is a HTTP request that a browser sends before the original CORS request to check whether the API Gateway server will permit the actual CORS request. CORS preflight request uses OPTIONS method and includes these headers as part of the request sent from the browser to API Gateway:

    1. Origin

    2. Access-Control-Request-Method

    3. Access-Control-Request-Headers

    The following flow chart explains the flow of the CORS preflight request received in API Gateway:

    The following table shows the various use cases of the CORS preflight request originating from browser and how API Gateway responds to each CORS preflight requests:

    # CORS Preflight request headers from browser Configured CORS Policy in API Gateway API Gateway sends the respective response to browser
    1

    Origin: http://test.com

    Access-Control-Request-Method : POST

    Access-Control-Request-Headers : test1,test2

    Access-Control-Allow-Origin : http://test2.com

    Access-Control-Allow-Methods : POST,GET,PUT

    Access-Control-Allow-Headers : test1,test2

    Sends 403 Specified Origin is not allowed status, as the Origin header (http://test.com) from the browser does not match with the Access-Control-Allow-Origin (http://test2.com) configured in the CORS policy.
    2

    Origin: http://test2.com

    Access-Control-Request-Method : DELETE

    Access-Control-Request-Headers : test1,test2

    Access-Control-Allow-Origin : http://test2.com

    Access-Control-Allow-Methods : POST,GET,PUT

    Access-Control-Allow-Headers : test1,test2

    Sends 405 Method Not Allowed status, as the Access-Control-Request-Method header (DELETE) from the browser does not match with the Access-Control-Allow-Methods (POST,GET,PUT) configured in the CORS policy.
    3

    Origin: http://test2.com

    Access-Control-Request-Method : POST

    Access-Control-Request-Headers : test3

    Access-Control-Allow-Origin : http://test2.com

    Access-Control-Allow-Methods : POST,GET,PUT

    Access-Control-Allow-Headers : test1,test2

    Sends 403 Header Not Supported, as the Access-Control-Request-Headers header (test3) from the browser does not match with the Access-Control-Allow-Headers (test1,test2) configured in the CORS policy.
    4

    Origin: http://test2.com

    Access-Control-Request-Method : POST

    Access-Control-Request-Headers : test1

    Access-Control-Allow-Origin : http://test2.com

    Access-Control-Allow-Methods : POST

    Access-Control-Allow-Headers : test1, test2

    Access-Control-Max-Age: 100

    Access-Control-Allow-Credentials : true

    Access-Control-Expose-Headers : header1,header2

    Sends 200 OK status with the following headers:
    • Access-Control-Allow-Origin : http://test2.com
    • Access-Control-Allow-Methods : POST,GET,PUT
    • Access-Control-Allow-Headers : test1,test2
    • Access-Control-Max-Age: 100
    • Access-Control-Allow-Credentials : true

    Since the origin, methods, and headers from the browser matches with configured CORS policy in API Gateway.

    5

    Origin: http://test2.com

    Access-Control-Request-Method : POST

    Access-Control-Request-Headers : test1

    Access-Control-Allow-Origin : http://test1.com

    Access-Control-Allow-Methods : POST

    Access-Control-Allow-Headers : test1, test2

    Access-Control-Max-Age: 100

    Access-Control-Allow-Credentials : true

    Access-Control-Expose-Headers : header1,header2

    In addition, if you have specified the Javascript origins in the application as http://test2.com

    Sends 200 OK status with the following headers:
    • Access-Control-Allow-Origin : http://test2.com
    • Access-Control-Allow-Methods : POST,GET,PUT
    • Access-Control-Allow-Headers : test1,test2
    • Access-Control-Max-Age: 100
    • Access-Control-Allow-Credentials : true

    Even though the origin header from the browser does not match with configured CORS policy, it matches with the configured javascript origins in the application.

    CORS Request

    A CORS request is a HTTP request that includes an Origin header. When API Gateway receives the CORS request, the Origin header in the CORS request is verified against the Access-Control-Allow-Origin configured in the CORS policy, if it matches then API Gateway allows to access the resources.

    The following flow chart explains the flow of the CORS request received in API Gateway:

    The following table shows the various use cases of the CORS request originating from browser and how API Gateway responds to each CORS requests:

    # CORS Request headers from browser Configured CORS Policy in API Gateway API Gateway sends the respective response to browser
    1

    Origin: http://test.com

    Access-Control-Allow-Origin : http://test2.com

    Access-Control-Allow-Methods : POST,GET,PUT

    Access-Control-Allow-Headers : test1,test2

    Access-Control-Max-Age: 100

    Access-Control-Allow-Credentials : true

    Access-Control-Expose-Headers : header1,header2

    Sends 403 Specified Origin is not allowed status, as the Origin header (http://test.com) from the browser does not match with the Access-Control-Allow-Origin (http://test2.com) configured in the CORS policy.
    2

    Origin: http://test2.com

    Access-Control-Allow-Origin : http://test2.com

    Access-Control-Allow-Methods : POST,GET,PUT

    Access-Control-Allow-Headers : test1,test2

    Access-Control-Max-Age: 100

    Access-Control-Allow-Credentials : true

    Access-Control-Expose-Headers : header1,header2

    Sends 200 OK status with the following headers:
    • Access-Control-Allow-Origin :

      http://test2.com

    • Access-Control-Allow-Credentials : true
    • Access-Control-Expose-Headers : header1,header2

    Since the Origin header (http://test2.com) from the browser matches with the Access-Control-Allow-Origin (http://test2.com) configured CORS policy in API Gateway.

    3

    Origin: http://test2.com

    Access-Control-Request-Method:POST

    Access-Control-Request-Headers:test1

    Access-Control-Allow-Origin : http://test1.com

    Access-Control-Allow-Methods : POST

    Access-Control-Allow-Headers : test1,test2

    Access-Control-Max-Age: 100

    Access-Control-Allow-Credentials : true

    Access-Control-Expose-Headers : header1,header2

    In addition, if you have specified the Javascript origins in the application as http://test2.com

    Sends 200 OK status with the following headers:
    • Access-Control-Allow-Origin: http://test2.com
    • Access-Control-Allow-Methods: POST,GET,PUT
    • Access-Control-Allow-Headers: test1,test2
    • Access-Control-Max-Age:100
    • Access-Control-Allow-Credentials : true

    Even though the origin header from the browser does not match with configured CORS policy, it matches with the configured javascript origins in the application.

    Note:

    • If native service supports CORS mechanism and if you have not configured the CORS policy in API Gateway, then API Gateway goes to pass-through security mode and forwards the CORS request to the native service.
    • If native service supports CORS mechanism and if you have also configured the CORS policy in API Gateway, then API Gateway takes precedence in handling the CORS request.

    Data Masking

    Data masking is a technique whereby sensitive data is obscured in some way to render it safe and to protect the actual data while having a functional substitute for occasions when the real data is not required.

    This policy is used to mask sensitive data at the application level. At the application level you must have an Identify and Access policy configured to identify the application for which the masking is applied. If no application is specified then it will be applied for all the other responses. Fields can be masked or filtered in the response messages to be sent. You can configure the masking criteria as required for the XPath, JSONPath, and Regex expressions based on the content-types. This policy can also be applied at the API scope level.

    The table lists the content-type and masking criteria mapping.

    Content-type Masking Criteria
    application/xml
    text/xml
    text/htm
    XPath
    application/json
    application/json/badgerfish
    JSONPath
    text/plain Regex

    The table lists the masking criteria properties that you can configure to mask the data in the response messages:

    Parameter Description
    Consumer Applications Optional. Specifies the applications for which the masking criterion has to be applied.

    Start typing the application name, select the application from the type-ahead search results displayed, and click icon to add one or more applications.

    For example: If there is a DataMasking(DM1) criteria created for application1 a second DataMasking(DM2) for application2 and a third DataMasking(DM3) with out any application, then for a request that comes from consumer1 the masking criteria DM1 is applied, for a request that comes from consumer2 DM2 is applied. If a request comes with out any application or from any other application except application1 and application2 DM3 is applied.

    You can use the delete icon icon to delete the added applications from the list.

    XPath. Specifies the masking criteria for XPath expressions in the response messages.
    Masking Criteria Click Add masking criteria and provide the following information and click Add:
    • Query expression. Specify the query expression that has to be masked or filtered.

      For example: /pet/details/status, /user/details/card/ccnumber.

    • Masking Type. Specifies the type of masking required. You select either Mask or Filter. Selecting Mask replaces the value with the given value (the default value being ********). Selecting Filter removes the field completely.
    • Mask Value. Appears if you have select the Masking Type selected is Mask. Provide a mask value.
    • You can add multiple masking criteria.

      As Query expression and Mask Value properties support variable framework, you can use the available variables.

      In case of query expression, if you provide variable syntax, the XPath is applied on the payload using the value that is resolved from the variable given.

      For example, if you provide a query expression as ${request.headers.myxpath} and the corresponding mask value as ${request.headers.var1} , and if the incoming request header myxpath is configured with value //ns:cardNumber, then the card number derived from the payload is masked with the header value in var1.

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

    • Namespace. Specifies the following Namespace information:
      • Namespace Prefix. The namespace prefix of the payload expression to be validated.
      • Namespace URI. The namespace URI of the payload expression to be validated
      Note: You can add multiple namespace prefix and URI by clicking icon.
    JSONPath. This is applicable only for REST API. Specifies the masking criteria for JSONPath expressions in the response messages.
    Masking Criteria Click Add masking criteria and provide the following information and click Add:
    • Query expression. Specify the query expression that has to be masked or filtered. For example: $.pet.details.status.
    • Masking Type. Specifies the type of masking required. You select either Mask or Filter. Selecting Mask replaces the value with the given value (the default value being ********). Selecting Filter removes the field completely.
    • Mask Value. Appears if you have select the Masking Type selected is Mask. Provide a mask value.
    • You can add multiple masking criteria.

      As Query expression and Mask Value properties support variable framework, you can use the available variables.

      In case of query expression, if you provide variable syntax, the JSONPath is applied on the payload using the value that is resolved from the variable given.

      For example, if you provide a query expression as ${request.headers.myjsonpath} and the corresponding mask value as ${request.headers.var1} , and if the incoming request header myjsonpath is configured with value $.cardNumber, then the card number derived from the payload is masked with the header value in var1.

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

    Regex. Specifies the masking criteria for regular expressions in the request messages.
    Masking Criteria Click Add masking criteria and provide the following information and click Add:
    • Query expression. Specify the query expression that has to be masked or filtered. For example: [0-9]+.
    • Masking Type. Specifies the type of masking required. You select either Mask or Filter. Selecting Mask replaces the value with the given value (the default value being ********). Selecting Filter removes the field completely.
    • Mask Value. Appears if you have select the Masking Type selected is Mask. Provide a mask value.
    • You can add multiple masking criteria.

      As Query expression and Mask Value properties support variable framework, you can use the available variables.

      In case of query expression, if you provide variable syntax, the regex is applied on the payload using the value that is resolved from the variable given.

      For example, if you provide a query expression as ${request.headers.myregex} and the corresponding mask value as ${request.headers.var1}, then the regex is applied using the value configured in the incoming request header myregex and the derived value is masked with the header value in var1.

    For details about the variables available in API Gateway, see Variables available in API Gateway.
    Apply for transaction Logging Select this option to apply masking criteria for transactional logs.

    When you select this option the transactional log for the response is masked on top of response sent to the client.

    Apply for payload Select this option to apply masking criteria for payload in the following scenarios:
    • Response received from the native service.
    • Response sent to the client.
    Note: When you select this option it automatically masks the data in the transactional log.

    Error Handling

    The policy in this stage enables you to specify the error conditions, lets you determine how these error conditions are to be processed. You can also mask the data while processing the error conditions. The policies included in this stage are:

    Conditional Error Processing

    Error Handling is the process of passing an exception message issued as a result of a run-time error to take any necessary actions. This policy returns a custom error message (and the native provider’s service fault content) to the application when the native provider returns a service fault. You can configure conditional error processing and use variables to create custom error messages.

    The table lists the properties that you can specify for this policy:

    Parameter Description
    Condition Conditions are used to specify when the policy has to be executed. We can add multiple conditions with logical operators. .

    Available values are:

    • AND. API Gateway transforms the error responses that comply with all the configured conditions
    • OR. This is selected by default. API Gateway transforms the error responses that comply with any one configured condition.
    • Click Add Condition and provide the following information and click icon.

    • Variable. Specifies the variable type with a syntax.
    • Operator. Specifies the operator to use to relate variable and the value. You can select one of the following:
      • Equal
      • Equals ignore case
      • Not equals
      • Not equals ignore case
      • Contains
      • Not Contains
      • Exists
      • Not Exists
      • Greater Than
      • Less Than
    • Value. Specifies a plain value or value with a syntax.

    For details about the variables available in API Gateway, see Variable Framework.

    Pre-Processing. Specifies how the native error response is to be processed before this policy processes it.
    Invoke webMethods Integration Server Service Specify the webMethods IS service to pre-process the error message.

    Provide the following information

    • webMethods IS Service. Specify the webMethods IS service to be invoked to pre-process the error messages. The list displays only the pre-shipped Integration Server services, which you can invoke to pre-process the service error message.

      You can add multiple entries for webMethods IS service by clicking icon.

    • Comply to IS Spec. Mark this as true if you want the input and the output parameters to comply to the IS Spec present in pub.apigateway.invokeISService.specifications folder in wmAPIGateway package.
    • webMethods IS Service alias. Start typing the webMethods alias name and select the alias from the type-ahead search results displayed to add one or more aliases.
    XSLT Transformation Provide the XSLT file and feature you want to use to transform the service error response.

    Click Browse to select the XSLT file and upload it.

    Provide the following information for the XSLT feature:
    • Feature Name. Specifies the name of the XSLT feature.
    • Feature Value. Specifies the value for the feature.

    You can add multiple entries for feature name and value by clicking icon.

    Note: API Gateway supports XSLT 1.0 and XSLT 2.0.
    Transformation Configuration. Specifies various transformations to be configured.
    Header Transformation Customizes the list of headers in the error response that is sent to the client.

    You can add or modify header parameters by providing the following information:

    • Variable. Specifies the variable type with a syntax.
    • Value. Specifies a plain value or value with a syntax.
    • You can add multiple variables and corresponding values by clicking icon.

      You can remove any header by typing the plain value or value with a syntax.

      For details about the variables available in API Gateway, see Variable Framework.

    Status Transformation Specifies the status transformation to be configured for the error responses.

    Provide the following information:

    • Code. Specifies the status code that is sent in the response to the client.
    • For example if you want to transform status code as 403, provide 403 in the Code field.

    • Message. Specifies the Status message that is sent in the response to the client.
    • For example *The data you are looking for is not found* can be used to transform the original *404 Not Found* status message.

    Define custom variables Defines a custom variable name to a complex variable expression or constant value. This can be particularly useful when you want to use this complex expression multiple times in the error payload transformation or when you want to use a short notation for a complex variable expression.

    Provide the following information:

    • Variable. Specifies the variable type with a syntax.
    • Value. Specifies a plain value or value with a syntax.

    For example if you provide a variable as id and the corresponding value as ${response.payload.jsonPath[$.id]}, this creates a custom variable that can be used in failure message transformation.

    For details about the variables available in API Gateway, see Variable Framework.

    Failure Message. Specifies how the error response sent by the native service is to be processed before sending the same to the application.
    Failure Messages Specifies the payload transformation to be configured for the error responses.
    • Click text and specify the payload to use to transform the error response messages as required.
    • Click json and specify the payload to use to transform the error response messages as required.
    • Click xml and specify the payload to use to transform the error response messages as required.

    • NOTE: For a SOAP API, select the type text and provide the failure message to be included in the faultstring of the SOAP response. Failure message in type json, xml are not used for the SOAP response.

      As this property supports variable framework, to transform the error response messages you can make use of the available variables in addition to the custom variables defined in this policy. For details about the variables available in API Gateway, see Variable Framework.

    • Click Send Native Provider Fault Message to send the native failure message to the application without applying payload transformation.
    Post-Processing. Specifies how the error response sent by the native service is to be processed before sending the same to the application.
    Invoke webMethods Integration Server Service Specify the webMethods IS Service for post-processing the error message.

    Provide the following information

    • webMethods IS Service. Specify the webMethods IS service to be invoked to post-process the error messages. The list displays only the pre-shipped Integration Server services, which you can invoke to post-process the service error message.

      You can add multiple entries for webMethods IS service by clicking icon.

    • Comply to IS Spec. Mark this as true if you want the input and the output parameters to comply to the IS Spec present in pub.apigateway.invokeISService.specifications folder in wmAPIGateway package.
    • webMethods IS Service alias. Start typing the webMethods alias name and select the alias from the type-ahead search results displayed to add one or more aliases.
    XSLT Transformation Provide the XSLT file that you want to use to transform the service error response.
    Provide the following information for the XSLT feature:
    • Feature Name. Specifies the name of the XSLT feature.
    • Feature Value. Specifies the value for the feature.

    You can add multiple entries for feature names and values by clicking icon.

    Note: API Gateway supports XSLT 1.0 and XSLT 2.0.
    Transformation Metadata. Specifies the metadata for transformation of the error responses received from the native API. For example, the namespaces configured in this section can be used when you provide the syntax for XPath ${response.payload.xpath} For example: ${response.payload.xpath[//ns:emp/ns:empName]}.
    Namespace Specifies the namespace information to be configured for transformation. This is applicable only for XML transformation.

    Provide the following information:

    • Namespace Prefix. The namespace prefix of the payload expression to be validated.

      For example, specify the namespace prefix as SOAP_ENV.

    • Namespace URI. The namespace URI of the payload expression to be validated.
    • For example, specify the namespace URI as http://schemas.xmlsoap.org/soap/envelope/. This declaration defines SOAP_ENV as an alias for the namespace: http://schemas.xmlsoap.org/soap/envelope/.

      You can add multiple namespace prefixes and URIs by clicking icon.

      You can add multiple namespace prefixes and URIs by clicking **+Add**.

    Data Masking

    Data masking is a technique whereby sensitive data is obscured in some way to render it safe and to protect the actual data while having a functional substitute for occasions when the real data is not required.

    This policy is used to mask sensitive data in the custom error messages being processed and sent to the application. Fields can be masked or filtered in the error messages. You can configure the masking criteria as required for the XPath, JPath, and Regex expressions. This policy can also be applied at the API scope level.

    The table lists the masking criteria properties that you can configure to mask the data in the request messages received:

    Parameter Description
    Consumer Applications Specifies the applications for which the masking criterion has to be applied.

    Start typing the application name, select the application from the type-ahead search results displayed, and click icon to add one or more applications.

    You can use the delete icon icon to delete the added applications from the list.

    XPath. Specifies the masking criteria for XPath expressions in the error messages.
    Masking Criteria Click Add masking criteria and provide the following information and click Add:
    • Query expression. Specify the query expression that has to be masked or filtered. For example: /soapenv:Fault/faultstring
    • Mask Value. Appears if you have select the Masking Type selected is Mask. Provide a mask value.
      You can add multiple masking criteria.

      As Query expression and Mask Value properties support variable framework, you can use the available variables.

      In case of query expression, if you provide variable syntax, the XPath is applied on the payload using the value that is resolved from the variable given.

      For example, if you provide a query expression as ${request.headers.myxpath} and the corresponding mask value as ${request.headers.var1} , and if the incoming request header myxpath is configured with value //ns:cardNumber, then the card number derived from the payload is masked with the header value in var1.

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

    • Namespace. Specifies the following Namespace information:
      • Namespace Prefix. The namespace prefix of the payload expression to be validated.
      • Namespace URI. The namespace URI of the payload expression to be validated
      Note: You can add multiple namespace prefix and URI by clicking icon.
    JSONPath. This is applicable only for REST API. Specifies the masking criteria for JSONPath expressions in the error messages.
    Masking Criteria Click Add masking criteria and provide the following information and click Add:
    • Query expression. Specify the query expression that has to be masked or filtered. For example: $.error.reason
    • Masking Type. Specifies the type of masking required. You select either Mask or Filter. Selecting Mask replaces the value with the given value (the default value being ********). Selecting Filter removes the field completely.
    • Mask Value. Appears if you have select the Masking Type selected is Mask. Provide a mask value.
    • You can add multiple masking criteria.

      As Query expression and Mask Value properties support variable framework, you can use the available variables.

      In case of query expression, if you provide variable syntax, the JSONPath is applied on the payload using the value that is resolved from the variable given.

      For example, if you provide a query expression as ${request.headers.myjsonpath} and the corresponding mask value as ${request.headers.var1} , and if the incoming request header myjsonpath is configured with value $.cardNumber, then the card number derived from the payload is masked with the header value in var1.

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

    Regex. Specifies the masking criteria for regular expressions in the error messages.
    Masking Criteria Click Add masking criteria and provide the following information and click Add:
    • Query expression. Specify the query expression that has to be masked or filtered. For example: (.*)
    • Masking Type. Specifies the type of masking required. You select either Mask or Filter. Selecting Mask replaces the value with the given value (the default value being ********). Selecting Filter removes the field completely.
    • Mask Value. Appears if you have select the Masking Type selected is Mask. Provide a mask value.
    • You can add multiple masking criteria.

      As Query expression and Mask Value properties support variable framework, you can use the available variables.

      In case of query expression, if you provide variable syntax, the regex is applied on the payload using the value that is resolved from the variable given.

      For example, if you provide a query expression as ${request.headers.myregex} and the corresponding mask value as ${request.headers.var1}, then the regex is applied using the value configured in the incoming request header myregex and the derived value is masked with the header value in var1.

    For details about the variables available in API Gateway, see Variables available in API Gateway.
    Apply for transaction Logging Select this option to apply masking criteria for transactional logs.

    When you select this option the transactional log for the response is masked on top of response sent to the client.

    Apply for payload Select this option to apply masking criteria for payload.

    When you select this option the payload in the response sent to the client is masked.

    Note: When you select this option it automatically masks the data in the transactional log.

    System Context Variables

    API Gateway provides predefined system context variables and you can declare your own custom context variables. Any context variable state defined during the inbound request processing steps is available during the outbound response processing steps. To set, get, or remove the predefined context variables, use The API for Context Variables provided in API Gateway.

    The table lists the predefined system context variables that you can configure in the conditional routing policy through the API Gateway user interface.

    System Context Variable Name Description
    User The identified API Gateway user for the current request.
    Inbound HTTP method The HTTP method used by the client to send the request.
    For example, GET, POST, PUT, DELETE, and PATCH.
    Routing method The HTTP method used by the routing policy when you select CUSTOM as the HTTP method.
    If you do not define this context variable, then the method used is from the Inbound HTTP method.
    Inbound content type Content type of the request.
    Inbound accept Accept header in the incoming request from the client.
    Inbound protocol The protocol of the request.
    For example, HTTP or HTTPS.
    Inbound request URI A partial reference to an API (for HTTP and HTTPS only). The protocol, host and port are not part of the value.For example, if the API is invoked: http://hostname/gateway/API then the expected value of this variable would be /gateway/API.
    For a REST API, the URL also includes query string parameters. For example, if the following API is invoked: http://hostname/gateway/cars?vin=1234 the expected value of this variable would be /gateway/cars?vin1234
    Inbound IP The client IP address used to send the request.
    Gateway hostname API Gateway host name.
    Gateway IP API Gateway IP address.
    Operation name Operation name for SOAP APIs.
    It is empty for REST API.
    Native Endpoint Retrieves the native endpoint in the incoming request from the client.

    The table lists the predefined context variables that you can set or get in API Gateway using an IS service. For details, see The API for Context Variables.

    Context Variable Name Description
    CONSUMER_APPLICATION The name of the consumer application accessing the API.
    INTERVAL_FAULT_COUNT The number of service faults for the interval.
    INTERVAL_SUCCESS_COUNT The number of success counts for a given API.
    INTERVAL_TOTAL_COUNT The total number of counts for a given service.
    AVG_SUCCESS_TIME The average amount of time it took the service to complete all invocations in the current interval. This is measured from the moment API Gateway receives the request until the moment it returns the response to the caller.
    Note:By default, average response time does not include metrics for failed invocations.
    FASTEST_SUCCESS_INVOKE Minimum Response Time.
    Note:By default, Minimum Response Time does not include metrics for failed invocations.
    SLOWEST_SUCCESS_INVOKE Maximum Response Time.
    Note:By default, Maximum Response Time does not include metrics for failed invocations.
    SOAP_HEADERS Contains an array of the SOAP header elements in the request.
    PROTOCOL_HEADERS Contains a map of key-value pairs in the request, where the values are provided as strings.
    SERVICE_NAME The name of the service.
    NATIVE_PROVIDER_ERROR The reason returned by the native provider in the case where it produced a SOAP fault. This will not contain API Gateway errors such as security policy enforcement errors. This variable only contains the reason text wrapped in a SOAP fault.
    Note:Note: When you use this variable in Conditional Error Processing message that you specify in the Response Processing step, note the following: if a request is denied due to security policy enforcement, the fault handler variable $ERROR_MESSAGE would contain a native service provider error message or other error messages that result from enforced security assertions. However, $NATIVE_PROVIDER_ERROR is null in this case.
    ROUTING_ENDPOINT API Gateway takes the ROUTING_ENDPOINT value from the message context and replaces the ${sys:dyn-Endpoint} variable in the Route Through field of dynamic routing policy configuration.

    The API for Context Variables

    API Gateway provides an API that you can use to:

    API Gateway provides the following JAVA services, which are defined in the class ISMediatorRuntimeFacade.java:

    pub.apigateway.ctxvar:getContextVariable

    Use this JAVA service to retrieve a context variable’s value and assign it to a pipeline variable. All parameter names are case-sensitive.

    Parameter Pipeline Type Data Type Description Examples
    MessageContext in Object ref This object is inserted into the pipeline by API Gateway. N/A
    varName in String Context variable name (system or custom). For system context variable, use just the variable name to get its value. For example, PROTOCOL_HEADERS.
    For custom context variable, use the prefix “mx:” with the variable name to get its value. For example, mx:CUSTOM_VAR.
    serValue out Object ref Java.io.serializable value. (Usually a string).  

    The table lists the predefined system context variables and its syntax used to get system context variables using pub.apigateway.ctxvar:getContextVariable.

    System Context Variable Name ctxVar IS Service Syntax Set or Get Supported
    User USER Supports get
    Inbound HTTP method INBOUND_HTTP_METHOD Supports get
    Routing method ROUTING_METHOD Supports get
    Inbound content type MESSAGE_TYPE Supports get
    Inbound accept BUILDER_TYPE Supports get
    Inbound protocol INBOUND_PROTOCOL Supports get
    Inbound request URI INBOUND_REQUEST_URI Supports get
    Inbound IP INBOUND_IP Supports get
    Gateway hostname MEDIATOR_HOSTNAME Supports get
    Gateway IP MEDIATOR_IP Supports get
    Operation name OPERATION Supports get
    Native Endpoint NATIVE_ENDPOINT Supports get.
    Note:This variable returns native endpoint value, only after Routing policy gets executed.
    Protocol headers PROTOCOL_HEADERS[xxx] Supports get
    SOAP headers SOAP_HEADERS[xxx] Supports get

    Notes on getting and setting the PROTOCOL_HEADERS

    All context variable values are typed as either string or int except for the predefined context variables, PROTOCOL_HEADERS, which is of the type IData. You can set or get value for PROTOCOL_HEADERS in one of the following ways:

    pub.apigateway.ctxvar:setContextVariable

    Use this JAVA service to set a value on a context variable. The pipeline variable containing the context variable value should be an object reference that implements java.io.Serializable. All parameter names are case-sensitive.

    Parameter Pipeline Type Data Type Description Examples
    MessageContext in Object ref This object is inserted into the pipeline by API Gateway. N/A
    varName in String Context variable name (predefined or custom). PROTOCOL_HEADERS
    mx:CUSTOM_VAR
    serValue in Object ref Java.io.serializable value. (Usually a string).

    pub.apigateway.ctxvar:declareContextVariable

    Use this JAVA service to declare a custom context variable. All custom-defined context variables must be declared in a custom namespace that is identified by using the prefix mx (for example, mx:CUSTOM_VARIABLE). All parameter names are case-sensitive.

    Note: It is not legal to use this service to declare the predefined context variables; you can only declare custom variables.

    Parameter Pipeline Type Data Type Description
    ctxVar in Object ref The document type defining the context variable object. Use the ctxVar Document Type provided in the JAVA service pub.apigateway.ctxvar:ctxVar and map it to this input variable. Define the name (for example, mx:CUSTOM_VARIABLE), the schema_type (string or int), and isReadOnly (true or false).
    ctxVar out Object ref The set Context variable document type.
    varNameQ out Object ref javax.xml.namespace.QName value. The QName of the variable.

    Note the following:

    pub.apigateway.ctxvar:removeContextVariable

    Use this JAVA service to remove a custom context variable from a request or response session. All parameter names are case-sensitive.

    Note: Keep the following points in mind:

    • It is not legal to use this service to remove any predefined context variables; you can only remove custom variables.
    • Attempting to remove a non-existent context variable will not result in an error.

    Parameter Pipeline Type Data Type Description Examples
    MessageContext in Object ref This object is inserted into the pipeline by API Gateway. N/A
    varName in String Custom context variable name. mx:CUSTOM_VAR

    Sample Flow Service: Getting a Context Variable Value

    This flow service sets the value of a custom context variable to be used in a response.

    This flow service declares a pipeline variable named customName, which is set to the value mx:COMP_TEST.

    This flow service will retrieve the context variable for customName and create an element for its context variable value in the response message return to the consumer.

    Step 1. Declaring customName

    icon

    We define the customName variable value to be mx:COMP_TEST so we can use this variable to lookup the custom variable name that was seeded in the previous example.

    Step 2. Setting customName to mx:COMP_TEST

    icon

    Clicking on the customName pipeline variable displays the name.

    Step 3. Displaying the value of customName

    icon

    The call to pub.mediator.ctxvar:getContextVariable retrieves the value of the custom context variable from the context variable map.

    Step 4. Calling meditor.ctxvar:getContextVariable

    icon

    This is just a sample JAVA service that takes the context variable and creates a top-level element in the response message using the same name and value.

    Step 5. Sample service using the context variable

    icon

    Sample Flow Service: Setting a Context Variable Value

    This flow service sets the value of a custom context variable to be used in a response.

    This flow service declares a pipeline variable named customName, which is set to the value mx:COMP_TEST.

    This flow service will retrieve the context variable for customName and create an element for its context variable value in the response message return to the consumer.

    Step 1. Declaring customName

    icon

    We define the customName variable value to be mx:COMP_TEST so we can use this variable to lookup the custom variable name that was seeded in the previous example.

    Step 2. Setting customName to mx:COMP_TEST

    icon

    Clicking on the customName pipeline variable will display the name.

    Step 3. Displaying the value of customName

    icon

    The call to pub.mediator.ctxvar:getContextVariable retrieves the value of the custom context variable from the context variable map.

    Step 4. Calling meditor.ctxvar:getContextVariable

    icon

    This is just a sample JAVA service that takes the context variable and creates a top-level element in the response message using the same name and value.

    Step 5. Sample service using the context variable

    icon

    Managing Global Policies

    Global policies are a set of policies that are associated globally to all APIs or the selected set of APIs. Global policies are supported for both SOAP and REST APIs.

    By associating policies globally to all APIs or the selected set of APIs, the administrator can ensure that a set of policies is applied to the selected APIs by default. The administrator can, for example, define a global policy that attaches a WS-Security (WSS) authentication to all SOAP API endpoints within a specific IP range. In this case, any client request from the specific IP range automatically inherits the security configuration defined in the global policy for SOAP APIs.

    Global Policy Matrix

    This table lists the stage-specific policies that can be configured as global policy for different types of APIs at the global level.

    Note: The Policy configuration page displays only the policies that are common to one or more API types selected in the global policy filter.

    Stages Policies
    Transport
  • Require HTTP/HTTPS - This policy can be enforced for all types of API. But the SOAP versions 1.1 and 1.2 are applicable only for SOAP-based APIs. The SOAP 1.1 and SOAP 1.2 sub types are not available in UI when the REST and ODATA APIs are selected.

  • Note: Software AG recommends to create a separate policy for each API type.
  • Set Media Type - This policy is applicable only for a REST request and the policy name is not listed in Policy configuration page when the SOAP and ODATA APIs are selected.
  • Identity & Access
    • Inbound Authentication - Transport, Authorize User, Identify and Authorize Application - These policies can be enforced to any API Type.
    • Inbound Authentication - Message - This policy is applicable only for SOAP-based APIs and the policy name is not listed in Policy configuration page when the REST and ODATA APIs are selected.
    Request Processing
    • Invoke webMethods IS, Validate API Specification, Data Masking - These policies can be enforced to any API Type.
    • Request Transformation - This policy is applicable only for SOAP and REST APIs. and not for ODATA services. When all three API types are selected, Request Transformation policy cannot be applied at the global level.
    Routing
    • Custom HTTP Header, Outbound Authentication - Transport, Outbound Authentication - Message. The Routing stage policies can be applied at a global level for all types of API.
    Traffic Monitoring
    • Log Invocation, Monitor Performance, Monitor SLA, Traffic Optimization, and Service Result Cache. The Traffic Monitoring stage policies can be applied at a global level for all types of API.
    Response Processing
    • Invoke webMethods IS, Validate API Specification, Data Masking - These policies can be enforced to any API Type.
    • Response Transformation - This policy can be enforced only for SOAP and REST APIs and the policy name is not listed in Policy configuration page when ODATA API type is selected.
    • CORS - This policy can be enforced only for REST and ODATA APIs and the policy name is not listed in Policy configuration page when SOAP-based API is selected.
    Error handling Conditional Error Processing and Data Masking. The Error handling stage policies can be applied at a global level for all types of API.

    Creating a Global Policy

    You must have the API Gateway’s manage global policies functional privilege assigned.

    To create a global policy you must perform the following high-level steps:

    1. Create a new global policy: During this step, you specify the basic details of the global policy.

    2. Optionally refine the scope of the policy: During this step, you can specify additional criteria to narrow the set of APIs to which the global policy applies.

    3. Configure the policies: During this step, you associate one or more policies, and assign values to each of the associated policy’s properties.

    4. Activate the policy: During this step, you put the new global policy into effect.

    To create a global policy

    1. Click Policies in the title navigation bar.

    2. Click the Global Policies tab.
      A list of all available global policies appears. A list of all available global policies appears. Use the Show drop-down list at the bottom of the page to set the maximum number of policies you want to display in a page.

    3. In the Policies page, click the Create Global Policy button.
      If you do not see the Create Global Policy button, it is probably because you do not have the API Gateway Administrator role to create a global policy in API Gateway.
      This opens the Create Global Policy page with the default Policy Details tab.

    4. In the Basic Information section, provide the required information for each of the displayed data fields:

      Field Description
      Name Name of the global policy.
      Description Description of the global policy.

      You can save the global policy by clicking Save at this stage and add the filters and policy configuration at a later time. .

    5. Click Continue to filters >. Alternatively, you can click Filters in the left navigation panel.

    6. To filter APIs by API type, select one or more API types. Available API types are REST, SOAP, and OData. The global policy would apply to the APIs specified by the filter.

    7. This is applicable to REST APIs. To filter APIs by HTTP methods, select one or more HTTP methods. Available HTTP methods are GET, POST, PUT, DELETE, PATCH, and HEAD. The global policy would apply to the APIs that have the methods specified by the filter.
      For details about the HTTP methods, see Refining the Scope of a Global Policy.

    8. To filter APIs by attributes:

      a. Select an attribute. Available attributes are API name, API description, API version, API tag, Resource/Operation tag, Method tag.

      b. Select a comparison operator.

      c. Specify the match string.

      d. Click + Add. You can add multiple criteria by clicking the + Add button and repeating the above steps.

      e. Select the logical conjunction (AND) or disjunction (OR) operation to apply when multiple criteria are specified for the global policy. The default value is AND.
      The global policy would apply to the APIs that match the attributes specified in the filter. For details about attributes, see Refining the Scope of a Global Policy.
      Example: To apply the global policy to APIs that match the criteria API name that contains pet and API tag that contains a, you can configure a filter as follows:

    9. To add multiple attribute filter groups, as required, click the +Add button. and specify the logical conjunction (AND) or disjunction (OR) operation to apply between filter groups. The global policy would apply to the APIs that match the filter groups specified in the filter.

      Example: To apply the global policy to APIs that match criteria API name that contains pet and API tag that contains a in filter group 1 and API version that equals 1 in filter group 2, you can configure a filter as follows:

      You can save the global policy by clicking Save at this stage and configure policies at a later time.

    10. Click Continue to policy configuration>. Alternatively, you can click the Policy configration tab.

    11. In the Policy configuration section, you can select the policies and configure the properties for each policy that you want API Gateway to enforce when it applies this global policy. For details, see Associating Policies to a Global Policy.

    12. Click Save. The global policy is created and displays the policy details page.

    You can now activate the global policy. For details, see Activating a Global Policy.

    Modifying the Scope of a Global Policy

    You must have the API Gateway’s manage global policies functional privilege assigned.

    Scope refers to the set of properties that determine a selected set of APIs for the enforcement of the policy. For a global policy, scope is determined by the policy’s property API Type in the Policy Details tab.

    API Type Description
    REST Global policy will be applied on all REST APIs in API Gateway.
    SOAP Global policy will be applied on all SOAP APIs in API Gateway.

    To modify the scope of a global policy

    1. Click Policies in the title navigation bar.

    2. Click the Global Policies tab.
      A list of all available global policies appears. Use the Show drop-down list at the bottom of the page to set the maximum number of policies you want to display in a page.

    3. Select the required policy.
      The Global Policy details page appears.

    4. Click Edit.
      If you do not see the Edit button, it is probably because you do not have the API Gateway Administrator role to modify the scope of a global policy in API Gateway.

    5. Select the policy’s Filters section, and specify the following:

      a. In the API Type property, select the API types (REST, SOAP, ODATA,or all) to which the policy will be applied.

      b. Optional. In the Filter using API attributes section, specify additional selection criteria to narrow the set of APIs to which this policy will be applied. For details, see Refining the Scope of a Global Policy.

    6. Click Save.

    Refining the Scope of a Global Policy

    You must have the API Gateway’s manage global policies functional privilege assigned.

    If you want to further restrict the set of APIs to which the global policy is applied, you can specify additional selection criteria in the Filter section of the API details page. Using the Filter section, you can filter APIs by Name, Description, Version attributes, HTTP Methods (applicable only for REST APIs), API tag (applicable for all selected API types), Resource/Operation tag (applicable for REST and SOAP APIs) and Method tag (applicable for a REST API). For details about the API types and their components for which you can add a tag, see Adding Tags to an API. If you specify no filter criteria, API Gateway applies the global policy to all the selected APIs.

    Filtering by Name, Description, Version, and Tag attributes

    You can filter APIs based on their Name, Description, Version, API tag, Resource/Operation tag, and Method attributes using any of the following comparison operators:

    Comparison Operators Description
    Equals Selects APIs whose Name, Description, Version, or Tag value matches a given string of characters. For example, use this operator to apply a policy only to REST APIs with the Name or Description value 4G Mobile Store.
    Not Equals Selects APIs whose Name, Description, Version, or Tag value does not match a given string of characters. For example, use this operator to apply a policy only to all REST APIs except those with the Name or Description value Mobile.
    Contains Selects APIs whose Name, Description, or Tag value includes a given string of characters anywhere within the attribute’s value. For example, use this operator to apply a policy to REST APIs that had the word Mobile anywhere in their Name or Description attribute.
    Starts with Selects APIs whose Name, Description, or Tag value begins with a given string. For example, use this operator to apply a policy only to REST APIs whose Name or Description begins with the characters 4G.
    Ends with Selects APIs whose Name, Description, or Tag value ends with a given string. For example, use this operator to apply a policy only to REST APIs whose Name or Description ends with the characters Store.

    When specifying match strings for the comparison operators described above, keep the following points in mind:

    Filtering by HTTP Methods (Applicable only for REST APIs)

    HTTP Methods Description
    GET Policy applies only to HTTP GET requests for any resource in the API. For example, use this option to apply a policy to resources of a REST API during an incoming GET request.
    POST Policy applies only to HTTP POST requests for any resource in the API. For example, use this option to apply a policy to resources of a REST API during an incoming POST request.
    PUT Policy applies only to HTTP PUT requests for any resource in the API. For example, use this option to apply a policy to resources of a REST API during an incoming PUT request.
    DELETE Policy applies only to HTTP DELETE requests for any resource in the API. For example, use this option to apply a policy to resources of a REST API during an incoming DELETE request.
    PATCH Policy applies only to HTTP PATCH requests for any resource in the API. For example, use this option to apply a policy to resources of a REST API during an incoming PATCH request.
    HEAD Policy applies only to HTTP HEAD requests for any resource in the API. For example, use this option to apply a policy to resources of a REST API during an incoming HEAD request.

    To refine the scope of a global policy

    1. Click Policies in the title navigation bar.

    2. Click the Global Policies tab.
      A list of all available global policies appears. Use the Show drop-down list at the bottom of the page to set the maximum number of policies you want to display in a page.

    3. Select the required policy.
      The Global Policy details page appears.

    4. Click Edit.
      If you do not see the Edit button, it is probably because you do not have the API Gateway Administrator role to refine the scope of a global policy in API Gateway.

    5. Click Filters.

    6. To filter by API types, select the API types by which you want to filter APIs.

    7. Applicable only for REST APIs. To filter by HTTP methods, in the Filter using HTTP methods section, select the HTTP methods by which you want to filter APIs with appropriate incoming requests.

    8. To filter by Name, Description, Version, or Tags perform the following steps in the Filter using attributes section:

      a. Select an attribute to filter the APIs to which you want to apply the global policy. Available attributes: API name, API description, API version, API tag, Resource/Operation tag, Method tag.

      b. Select the comparison operator.

      c. Specify the match string in the third field.

      d. To specify additional criteria, click the Add button and repeat the above steps.

      e. Select the logical conjunction (AND) or disjunction (OR) operation to apply when multiple criteria are specified for the global policy. The default value is AND.

      You can add multiple attribute filter groups by clicking the +Add button. You can also specify the logical conjunction (AND) or disjunction (OR) operation to apply between filter groups.

    9. Click Save to save the updated policy.

    Associating Policies to a Global Policy

    You must have the API Gateway’s manage global policies functional privilege assigned.

    The Policy Configuration tab on the Global Policy details page specifies the policy stages and the list of policies (applicable for each stage) that you want API Gateway to execute when it enforces the global policy.

    When modifying the list of policies for a global policy, API Gateway validates the policies to ensure that there are no policy conflicts.

    To modify the list of policies of a global policy

    1. Click Policies in the title navigation bar.

    2. Click the Global Policies tab.
      A list of all available global policies appears. Use the Show drop-down list at the bottom of the page to set the maximum number of policies you want to display in a page.

    3. Select the required policy.
      The Global Policy details page appears.

    4. Click Edit.
      If you do not see the Edit button, it is probably because you do not have the API Gateway Administrator role to modify the list of policies of a global policy in API Gateway.

    5. Select the policy’s Policy Configuration tab.
      The policy information is provided in the following sections:

      • Policy catalog - Transport, Identify and Access, Request Processing, Routing, Traffic Monitoring, Response Processing, Error Handling

      • Infographic - List of applied policies

      • Policy properties - Collection of policy properties

    6. In the Policy catalog section, click the chevron to expand the required policy stage.
      This displays a list of policies that are classified under the particular stage.

    7. In the expanded list of policies, select the policies that you want API Gateway to execute when it applies this global policy. To select a policy, click the Add (+) icon next to the policy name. The selected policies are displayed in the Infographic section.
      When you select the policies for the global policy, keep the following points in mind:

      • The policies shown in the Policy catalog section are determined by the API types that you have specified on the Filters section of the Global Policy Details page.
        If you do not see a policy that you need, that policy is probably not compatible with the API type that you selected in the Filters section.

      • If necessary, you can click the Policy Details tab and change your API type selection.

      Use the x icon in any individual policy to remove that particular policy from the Infographic section.

    8. To configure the properties for any new policies that you might have added to the Infographic section in the preceding steps or to make any necessary updates to the properties for existing policies in the global policy, see Configuring Properties for a Global Policy.

    9. Click Save.

    10. Click icon to view the complete list of policies in the updated policy.
      The Overview button is located in the lower right-corner of the Infographic section.
      To exit the overview, click the Close icon.

    Configuring Properties for a Global Policy

    You must have the API Gateway’s manage global policies functional privilege assigned.

    The Policy Configuration tab on the Global Policy details page specifies the list of policies that are applicable for each policy stage in the Policy catalog section. Each policy in the Infographic section has properties that you must set to configure the policy’s enforcement behavior.

    To configure the properties for a global policy

    1. Click Policies in the title navigation bar.

    2. Click the Global Policies tab.
      A list of all available global policies appears. Use the Show drop-down list at the bottom of the page to set the maximum number of policies you want to display in a page.

    3. Select the required policy.
      The Global Policy details page appears.

    4. Click Edit.
      If you do not see the Edit button, it is probably because you do not have the API Gateway Administrator role to configure the properties of a global policy in API Gateway.

    5. Select the policy’s Policy Configuration tab.
      The policy information is provided in the following sections:

      • Policy catalog - Transport, Identify and Access, Request Processing, Routing, Traffic Monitoring, Response Processing, Error Handling

      • Infographic - List of applied policies

      • Policy properties - Collection of policy properties

    6. In the Policy catalog section, click the chevron to expand the required policy stage. This displays a list of policies that are classified under the particular stage.

    7. In the Infographic section, do the following for each policy in the list:

      a. Select the policy whose properties you want to examine or set.

      b. In the Policy properties section, set the values for the policy’s properties as necessary.

      Note: Required properties are marked with an asterisk.

    8. Click Open in full-screen to view the policy’s properties in full screen mode.
      The Open in full-screen link is located in the upper right-hand corner of the Policy Configuration tab. Set the properties of the displayed policy, and then click OK.

      To exit out of full screen mode, click the Minimize icon.

    9. Click Save.

    10. Click icon to view the complete list of policies in the updated policy.
      The Overview button is located in the lower right-corner of the Infographic section. To exit the overview, click the Close icon.

    Viewing List of Global Policies and Policy Details

    The Global Policies tab displays a list of all globally available policies in API Gateway. Global policies are listed alphabetically by name.

    In addition to viewing the list of policies, you can also examine the details of a policy, create a copy of the template, activate, and delete a global policy in the Global Policies tab.

    To view the policy list and properties of a global policy

    1. Click Policies in the title navigation bar.

    2. Click the Global Policies tab.
      A list of all available global policies appears. Use the Show drop-down list at the bottom of the page to set the maximum number of policies you want to display in a page.

      The Global Policies tab provides the following information about each policy:

      Column Description
      Name Name of the global policy.
      Description The description for the global policy.

      You can also perform the following operations on a global policy:

      • Activate a policy to begin enforcing runtime behaviors.

      • Deactivate a policy to suspend enforcement of runtime behaviors.

      • Create a new copy of the policy.

      • Delete a policy to remove it from API Gateway.

    3. Select the required policy whose details you want to examine.
      The Global Policy details page appears. The policy details are displayed in the following tabs:

      • Policy Details: This tab contains a summary of basic information such as name, description, scope of the policy as to when the policy will apply, applicable APIs, and other information.

      • Policy Configuration: This tab contains the policy stages, applied policies, as well as the configuration details of individual policies.

    Modifying Global Policy Details

    You must have the API Gateway’s manage global policies functional privilege assigned.

    You use the Global Policy details page to examine and modify the properties of a policy.

    When modifying the details of a global policy, keep the following points in mind:

    To modify the properties of a global policy

    1. Click Policies in the title navigation bar.

    2. Click the Global Policies tab.
      A list of all available global policies appears. Use the Show drop-down list at the bottom of the page to set the maximum number of policies you want to display in a page.

    3. Select the required policy.
      The Global Policy details page appears. The policy details are displayed in the following tabs:

      • Policy Details: This tab contains a summary of basic information such as name, description, scope of the policy as to when the policy will apply, applicable APIs, and other information.

      • Policy Configuration: This tab contains the policy stages, applied policies, as well as the configuration details of individual policies.

    4. Click Edit.
      If you do not see the Edit button, it is probably because you do not have the API Gateway Administrator role to modify the properties of a global policy in API Gateway.

    5. On the Policy Details tab, modify the basic properties, selection criteria, and the applicable APIs as necessary.

    6. On the Policy Configuration tab, modify the policy list and the policy’s configuration properties as necessary.

    7. When you have completed the required modifications in the Global Policy details page, click Save to save the updated policy.

    8. Click Overview to view the complete list of policies in the updated policy.
      The Overview button is located in the lower right-corner of the Infographic section. To exit the overview, click the Close icon.

    Activating a Global Policy

    You must have the API Gateway’s activate global policies functional privilege assigned.

    Global policies are not enforced until they are activated.

    When you activate a global policy, be aware that:

    To determine whether a global policy is active or inactive, examine the policy’s Active indicator on the Policies > Global Policies tab. The icon in the Active column indicates the policy’s activation state as follows:

    Icon Description
    icon Policy is active.
    icon Policy is inactive.

    The activation state of a policy is also reported in the Global Policy Details page.

    To activate a global policy

    1. Click Policies in the title navigation bar.

    2. Click the Global Policies tab.
      A list of all available global policies appears. Use the Show drop-down list at the bottom of the page to set the maximum number of policies you want to display in a page.

    3. Select the required policy.
      The Global Policy details page appears.

    4. Click Activate.
      If you do not see the Activate button, it is probably because you do not have the API Gateway Administrator role to activate a global policy, or the policy is already in an Active state in API Gateway.

    Deactivating a Global Policy

    You must have the API Gateway’s activate global policies functional privilege assigned.

    Deactivating a global policy causes API Gateway to suppress enforcement of the policy.

    You usually deactivate a policy to suspend enforcement of a particular policy (temporarily or permanently).

    To deactivate a policy, you change the policy to the Inactive state. At a later time, you can begin enforcing a global policy by switching it to the Active state as described in Activating a Global Policy.

    When you deactivate a global policy, be aware that:

    To determine whether a global policy is active or inactive, examine the policy’s Active indicator on the Policies > Global Policies tab. The icon in the Active column indicates the policy’s activation state as follows:

    Icon Description
    icon Policy is active.
    icon Policy is inactive.

    The deactivation state of a policy is also reported in the Global Policy Details page.

    To deactivate a global policy

    1. Click Policies in the title navigation bar.

    2. Click the Global Policies tab.
      A list of all available global policies appears. Use the Show drop-down list at the bottom of the page to set the maximum number of policies you want to display in a page.

    3. Select the required policy.
      The Global Policy details page appears.

    4. Click Deactivate.
      If you do not see the Deactivate button, it is probably because you do not have the API Gateway Administrator role to deactivate a global policy, or the policy is already in an Inactive state in API Gateway.

    Deleting a Global Policy

    You must have the API Gateway’s manage global policies functional privilege assigned.

    You delete a global policy to remove it from API Gateway permanently.

    To delete a global policy, the following conditions must be satisfied:

    To delete a global policy

    1. Click Policies in the title navigation bar.

    2. Click the Global Policies tab.
      A list of all available global policies appears. Use the Show drop-down list at the bottom of the page to set the maximum number of policies you want to display in a page.

    3. Click the Delete icon icon for the required policy.
      If you do not see the Delete button, it is probably because you do not have the API Gateway Administrator role to delete a global policy, or the policy is in an Active state in API Gateway.

    4. Click Yes in the confirmation dialog.

    Copying a Global Policy

    You must have the API Gateway’s manage global policies functional privilege assigned.

    A global policy can become quite complex, especially if it includes many policies. Instead of creating a new policy from scratch, it is sometimes easier to copy an existing policy that is similar to the one you need and edit the copy.

    When you create a copy of a global policy, be aware that:

    In general, a copied policy is no different from a policy that you create from scratch.

    To copy a global policy

    1. Click Policies in the title navigation bar.

    2. Click the Global Policies tab.
      A list of all available global policies appears. Use the Show drop-down list at the bottom of the page to set the maximum number of policies you want to display in a page.

    3. Click the Copy icon for the required policy.
      If you do not see the Copy button, it is probably because you do not have the API Gateway Administrator role to create the copy of a global policy in API Gateway.

    4. In the Copy of Global Policy dialog box, provide the required information for each of the displayed data fields:

      Field Description
      Name Name of the global policy.
      API Gateway automatically adds the name of the existing global policy to the Name field. You can change the name of the policy to suit your needs. But you cannot leave this field empty.
      Description The description for the global policy.
    5. Click Copy to save the new policy.

    6. Modify the new policy as necessary and then save it.

      Activate the new policy when you are ready to put it into effect.

    Exporting Global Policies

    You must have the API Gateway’s export assets functional privilege assigned.

    Note: For more information about exporting and importing global policies, see Overview.

    To export the global policies

    1. Click Policies in the title navigation bar.

    2. Select Global Policies.

    3. Click icon to export a single policy.
      Alternatively, you can select multiple APIs to be exported simultaneously by clicking the checkboxes adjacent to the names of the API.

      Click icon and select Export from the drop-down list.

      The browser prompts you to either open or save the export archive.

    4. Select the appropriate option and click OK.

    Managing API-level Policies

    The API-level policies apply to all APIs at the API level within an instance of API Gateway.

    A policy at an API-level provides run-time governance capabilities to an API. The policy can be used to identify and authenticate consumers, validate digital signatures, capture performance measurements, and so on. Policies have one or more properties, which you can configure in a policy when you apply it to an API. For example, a policy that identifies consumers specifies one or more identifiers to identify the consumers who are trying to access the API.

    The API level policies are categorised in the following stages:

    Assigning a Policy to an API

    Ensure that the API is in Edit mode before you start assigning a policy to the API.

    To assign a policy to an API

    1. Click APIs in the title navigation bar.

    2. Select the required API.

    3. Click the Policies tab.

    4. Select the policy stage and the required policy.
      The policy is displayed in the infographic with its properties displayed in properties section.

    5. Provide the properties for the selected policy.

    6. Click Save.
      The policy is assigned to the API.

    Viewing API Policy Details

    The Policies tab on the API details page specifies the set of policies that are applied for that particular API.

    The API can have a set of policies that are configured globally through a policy, or directly through a policy template or a scope-level policy.

    The global policy in an API details page has each of its policies differentiated using a specific icon from the rest of the policies that are defined at the API-level and scope-level. The icon in the policy indicates the Inbound Authentication - Transport policy’s enforcement level within an API:

    Icon Description
    icon Policy is applied from a global policy. This policy is applicable across all resources / methods / operations of all APIs.
    icon Policy is applied from a policy template or at the API definition. This policy is applicable across all resources / methods / operations of that particular API.
    icon Policy is applied for the API’s scope. This policy is applicable across a set of resources / methods / operations of that particular API.
    icon Policy is applied through an active package definition. This policy is applicable across all resources / methods / operations of that particular API.

    Unlike the policy defined at API-level or scope-level, the policy defined as part of a global policy cannot be edited or deleted through the details page of an API.

    To view the policy details of an API

    1. Click APIs in the title navigation bar. A list of all registered APIs appears.

    2. Select the required API.

    3. Click the Policies tab. The Infographic view displays policies configured for the API.

      When this API is associated with one or more plans through active packages, a list of the Identify and Authorize Application policies and Threat Protection policies that are inherited from the corresponding plans and enforced on the API also appears. The inherited policies are differentiated using the package icon icon. The Identify and Authorize Application policy, always, has the Identification Type set to API Key.

    4. Click icon. A list of all available policies enforced on the API appears.

    Modifying API Policy Details

    Ensure that the API is in Edit mode before you modify a policy that is assigned to the API.

    To modify the policy details of an API

    1. Click APIs in the title navigation bar.

    2. Select the required API.

    3. Click the Policies tab.

    4. Select the policy stage, and the required policy.
      The Infographic view displays policies configured for the API.

    5. You can do one of the following:

      • Add more policies to the API. Select the policy stage and add the required policy. Configure the properties for the newly added policy as required.

      • Modify the already configured policy. Click the Edit icon. Select the required policy and modify the properties as required.

      • Delete policies from the API. To remove a policy, click the x icon.

    6. Click Save.

    Managing Scope-level Policies

    You can define policies at the API-level or scope-level for an API. API-level policies are processed for all incoming requests to the API. Scope-level policies are processed only for incoming requests that apply to a specific scope in the API. Any policy you specify at the API-level is overridden by the policy defined at the scope-level if the policies are the same. In contrast, the API-level policies will not affect the scope-level policies. But if there are policies applied at the global-level (through a global policy) for the API, then those policies will override every other policy configured at the API-level.

    The scope-level policies for an API provide a granular enforcement of policies at the resource-level, method-level, or both for the REST API, or at the operation-level for the SOAP API.

    Note: Scope-level policies are not supported for OData APIs.

    An API can have zero or more scope-level policies. When you define the scope-level policies for an API, keep the following points in mind:

    API Gateway supports scope-level policies only for the following stages:

    For information on the usage scenarios of policies configured for the scopes of an API, see Example: Usage Scenarios of API Scopes.

    Creating a Scope-level Policy

    You create a policy for the API scope, to enforce the specific set of policies on a collection of resources, methods, or both, or operations that are associated to the scope. An API can have zero or more scope-level policies.

    To create a scope-level policy

    1. Click APIs in the title navigation bar.
      This displays a list of APIs available in API Gateway.

    2. Click the name of the required API.
      This opens the API details page.

    3. Click Edit.
      If the API is active, API Gateway displays a warning message to let you know that the API is active.

    4. Click the Policies tab.
      This displays a list of scopes and policies available in the API.

    5. In the API Scope box, select the scope for that you want to create a policy.

    6. In the Policy catalog section, click the chevron to expand the required policy stage.
      This displays a list of policies that are classified under the particular stage.

    7. In the expanded list of policies, select the policies that you want to associate with this scope. To select a policy, click the Add (+) icon next to the policy name. The selected policies are displayed in the Infographic section.

      When you select the policies for the scope-level policy, keep in mind that the policies shown in the Policy catalog section are determined by the type of the displayed API. If you do not see a policy that you need, that policy is probably not compatible with this API.

      Use the Delete (X) icon in any individual policy to remove that particular policy from the Infographic section.

    8. In the Infographic section, do the following for each policy in the list:

      a. Select the policy whose properties you want to examine or set.

      b. In the Policy properties section, set the values for the policy’s properties as necessary.

      Note: Required properties are marked with an asterisk.

    9. Click Open in full-screen to view the policy’s properties in full-screen mode.
      The Open in full-screen link is located in the upper right-corner of the Policies tab.

    10. Set the properties of the displayed policy, and then click OK.
      To exit out of full-screen mode, click the Minimize icon.

    11. Click Save to create the new scope-level policy.
      Click icon to view the complete list of policies in the updated API. Activate the API, if it is not active, to put it into effect.

    Viewing List of Scope-level Policies and Policy Details

    The Infographic section displays the list of policies that are associated to a selected scope in the API’s Policies tab.

    To view the scope-level policies and properties of a policy

    1. Click APIs in the title navigation bar.
      This displays a list of APIs available in API Gateway.

    2. Click the name of the required API.
      This opens the API details page.

    3. Click the Policies tab.
      This displays a list of scopes and policies available in the API.

    4. In the API Scope box, select the scope whose policy details you want to examine.

    5. In the Infographic section, do the following for each policy in the list:

      a. Select the policy whose properties you want to examine.

      b. In the Policy properties section, examine the values for the policy’s properties as required.

    6. Click Open in full-screen to view the policy’s properties in full-screen mode.

      The Open in full-screen link is located in the upper right-corner of the Policies tab. Examine the properties of the displayed policy, and then click OK.

      To exit out of full-screen mode, click the Minimize icon.

    7. Click icon to view the complete list of policies in the updated API.
      The Overview button is located in the lower right-corner of the Infographic section.

      To exit the overview, click the Close icon.

    Modifying Scope-level Policy Details

    The API can have a set of policies that are configured globally through a global policy, or directly through a policy template, or a set of individual policies at the API-level or scope-level.

    To customize the policy configurations at the scope-level, you need to apply the policies that are available for the API’s scope, and then configure the properties of the individual policies to suit the needs of runtime behavior of that particular API.

    You use the Policies tab to examine and modify the properties of a policy at the scope-level.

    To modify the properties of a scope-level policy

    1. Click APIs in the title navigation bar.
      This displays a list of APIs available in API Gateway.

    2. Click the name of the required API.
      This opens the API details page.

    3. Click Edit.
      If the API is active, API Gateway displays a warning message to let you know that the API is active.

    4. Click the Policies tab.
      This displays a list of scopes and policies available in the API.

    5. In the API Scope box, select the scope whose policy details you want to modify.

    6. In the Infographic section, modify the policy list and the policy’s configuration properties as necessary.

      Use the Delete (X) icon in any individual policy to remove that particular policy from the Infographic section.

    7. Click Open in full-screen to view the policy’s properties in full-screen mode.
      The Open in full-screen link is located in the upper right-corner of the Policies tab.

    8. Modify the properties of the displayed policy, and then click OK.
      To exit full-screen mode, click the Minimize icon.

    9. When you have completed the required modifications for the scope-level policy, click Save to save the updated scope-level policy.
      Click icon to view the complete list of policies in the updated API. Activate the API, if it is not active, to put it into effect.

    Deleting a Scope-level Policy

    You delete a policy at the scope-level to remove the association between the policy and a scope.

    When deleting a scope-level policy in the API details page, keep the following point in mind:

    To delete a scope-level policy

    1. Click APIs in the title navigation bar.
      A list of all registered APIs appears.

    2. Select the required API.
      This opens the API details page.

    3. Click Edit.
      If the API is active, API Gateway displays a warning message to let you know that the API is active.

    4. Click the Policies tab.
      A list of scopes and policies available with the API appears.

    5. In the API Scope box, select the scope whose policy you want to remove.

    6. In the Infographic section, click the x icon in any individual policy to remove that particular policy from the scope.

    7. When you have removed the policy, click Save to save the updated scope-level policy.
      Click icon to view the complete list of policies in the updated API. Activate the API, if it is not active, to put it into effect.

    Managing Policy Templates

    Policy templates are a set of policies that can be associated directly with an individual API. The direct association of the policy template with an API provides the flexibility to alter the policy’s configurations to suit the individual API requirements.

    To apply a policy template to an API, modify the details page of the API, and apply the selected policy template.

    Creating a Policy Template

    You must have the API Gateway’s manage policy templates functional privilege assigned.

    To create a policy template, you must perform the following high-level steps:

    1. Create a new policy template: During this step, you specify the basic details of the policy template.

    2. Configure the policies: During this step, you associate one or more policies with the template, and assign values to each of the associated policy’s properties.

    To create a policy template

    1. Click Policies in the title navigation bar.

    2. Click the Policy Templates tab.
      A list of all available policy templates appears. Use the Show drop-down list at the bottom of the page to set the maximum number of policies you want to display in a page.

    3. In the Policies page, click the Create Policy Template button.
      This opens the Create Policy Template page with the default Policy Details tab.

    4. In the Basic Information section, provide the required information for each of the displayed data fields:

      Field Description
      Name Name of the policy template.
      Description Description of the policy template.
    5. Click Continue to policy configuration.

    6. In the Policy Configuration tab, select the policies and configure the properties for each policy that you want API Gateway to execute when it applies this policy template. For details, see Associating Policies with a Policy Template and Configuring Properties for a Policy Template.

    7. Click Save.

    Associating Policies with a Policy Template

    You must have the API Gateway’s manage policy templates functional privilege assigned.

    The Policy Configuration tab on the Policy Template details page specifies the set of policy stages and the list of policies (applicable for each stage).

    To modify the list of policies of a policy template

    1. Click Policies in the title navigation bar.

    2. Click the Policy Templates tab.
      A list of all available policy templates appears. Use the Show drop-down list at the bottom of the page to set the maximum number of policies you want to display in a page.

    3. Select the required template.
      The Policy Template details page appears.

    4. Click Edit.

    5. Click the Policy Configuration tab.
      The policy template information is provided in the following sections:

      • Policy catalog - Transport, Identify and Access, Request Processing, Routing, Traffic Monitoring, Response Processing, Error Handling

      • Infographic - List of applied policies

      • Policy properties - Collection of policy properties

    6. In the Policy catalog section, click the chevron to expand the required policy stage.
      This displays a list of policies that are classified under the particular stage.

    7. In the expanded list of policies, select the policies that you want API Gateway to execute when it applies this policy template. To select a policy, click the Add (+) icon next to the policy name. The selected policies are displayed in the Infographic section.

      Use the Delete (X) icon in any individual policy to remove that particular policy from the Infographic section.

    8. To configure the properties for any new policies that you might have added to the Infographic section in the preceding steps or to make any necessary updates to the properties for existing policies in the policy template, see Configuring Properties for a Policy Template.

    9. When the list of policies is complete and you have configured all of the properties for the policies correctly, click Save to save the updated policy template.

    10. Click icon to view the complete list of policies in the updated policy template. The Overview button is located in the lower right-corner of the Infographic section. In addition, you can view the configured properties for the individual policies.

      To exit the overview, click the Close icon.

    Configuring Properties for a Policy Template

    You must have the API Gateway’s manage policy templates functional privilege assigned.

    The Policy Configuration tab on the Policy Template details page specifies the list of policies that are applicable for each policy stage in the Policy catalog section. Each policy in the Infographic section has properties that you must set to configure the policy’s enforcement behavior.

    To configure the properties for a policy template

    1. Click Policies in the title navigation bar.

    2. Click the Policy Templates tab.
      A list of all available policy templates appears. Use the Show drop-down list at the bottom of the page to set the maximum number of policies you want to display in a page.

    3. Select the required template.
      The Policy Template details page appears.

    4. Click Edit.

    5. Click the Policy Configuration tab.
      The policy template information is provided in the following sections:

      • Policy catalog - Transport, Identify and Access, Request Processing, Routing, Traffic Monitoring, Response Processing, Error Handling

      • Infographic - List of applied policies

      • Policy properties - Collection of policy properties

    6. In the Policy catalog section, click the chevron to expand the required policy stage.
      This displays a list of policies that are classified under the particular stage.

    7. In the Infographic section, do the following for each policy in the list:

      a. Select the policy whose properties you want to examine or set.

      b. In the Policy catalog section, set the properties as necessary.

      Note: Required properties are marked with an asterisk.

    8. Click Open in full-screen to view the policy’s properties in full screen mode.
      The Open in full-screen link is located in the upper right-hand corner of the Policy Configuration tab. Set the properties of the displayed policy, and then click OK.

      To exit full screen mode, click the Minimize icon.

    9. After you configure the properties for all the policies in the Infographic section, click Save to save the updated policy template.

    10. Click icon to view the complete list of policies in the updated policy template. The Overview button is located in the lower right-corner of the Infographic section.

      To exit the overview, click the Close icon.

    Viewing List of Policy Templates and Template Details

    The Policy Templates tab displays a list of all available policy templates in API Gateway. Policy templates are listed alphabetically by name.

    In addition to viewing the list of policy templates, you can also examine the details of a template, create a copy of the template, and delete a policy template in the Policy Templates tab.

    To view the policy template list and properties of a policy template

    1. Click Policies in the title navigation bar.

    2. Click the Policy Templates tab.
      A list of all available policy templates appears. Use the Show drop-down list at the bottom of the page to set the maximum number of policies you want to display in a page.
      This tab provides the following information about each template:

      Column Description
      Name Name of the policy template.
      Description The description for the policy template.

      You can also perform the following operations on a policy template:

      • Create a new copy of the policy template.

      • Delete a policy template to remove it from API Gateway.

    3. Select the required policy template.
      The Policy Template details page appears. The policy template details are displayed in the following tabs:

      • Policy Details: This tab contains a summary of basic information such as the name and description of the policy template.

      • Policy Configuration: This tab contains the policy stages, applied policies, as well as the configuration details of individual policies.

    Modifying Policy Template Details

    You must have the API Gateway’s manage policy templates functional privilege assigned.

    You use the Policy Template details page to examine and modify the properties of a policy template.

    To modify the properties of a policy template

    1. Click Policies in the title navigation bar.

    2. Click the Policy Templates tab.
      A list of all available policy templates appears. Use the Show drop-down list at the bottom of the page to set the maximum number of policies you want to display in a page.

    3. Select the required template.
      The Policy Template details page appears. The policy template details are displayed in the following tabs:

      • Policy Details: This tab contains a summary of basic information such as name and description of the policy template.

      • Policy Configuration: This tab contains the policy stages, applied policies, as well as the configuration details of individual policies.

    4. Click Edit.

    5. On the Policy Details tab, modify the basic properties of the policy as necessary.

    6. On the Policy Configuration tab, modify the policy list and the policy’s configuration properties as necessary.

    7. When you have completed the required modifications on the Policy Template details page, click Save to save the updated policy template.

      If update of a policy template fails, API Gateway displays a pop-up style error message.

    8. Click Overview to view the complete list of policies in the updated policy template.
      The Overview button is located in the lower right-corner of the Infographic section.

      To exit the overview, click the Close icon.

    Deleting a Policy Template

    You must have the API Gateway’s manage policy templates functional privilege assigned.

    You delete a policy template to remove it from API Gateway permanently.

    To delete a policy template

    1. Click Policies in the title navigation bar.

    2. Click the Policy Templates tab.
      A list of all available policy templates appears. Use the Show drop-down list at the bottom of the page to set the maximum number of policies you want to display in a page.

    3. Click the Delete (icon) icon for the required template.

    4. Click Yes in the confirmation dialog.

    Copying a Policy Template

    You must have the API Gateway’s manage policy templates functional privilege assigned.

    A policy template can become quite complex, especially if it includes many policies. Instead of creating a new policy template from scratch, it is sometimes easier to copy an existing template that is similar to the one you need and edit the copy.

    When you create a copy of a policy template, be aware that:

    In general, a copied policy template is no different from a policy template that you create from scratch.

    To copy a policy template

    1. Click Policies in the title navigation bar.

    2. Click the Policy Templates tab.
      A list of all available policy templates appears. Use the Show drop-down list at the bottom of the page to set the maximum number of policies you want to display in a page.

    3. Click the Copy icon for the required template.

    4. In the Copy of Policy Template dialog box, provide the required information for each of the displayed data fields:

      Field Description
      Name Name of the policy template.

      API Gateway automatically adds the name of the existing policy template to the Name field. You can change the name of the template to suit your needs. But you cannot leave this field empty.
      Description The description for the policy template.
    5. Click Copy to save the new policy template.

    6. Modify the new policy template as necessary and then save it.

    Applying a Policy Template on the API Details Page

    You must have the API Gateway’s manage APIs functional privilege assigned.

    The Policies tab on the API details page specifies the set of policies that API Gateway executes when an application requests access to that particular API.

    The API can have a set of policies that are applied through a global policy, through a policy template, through a scope-level policy, and through API-level policies.

    To customize the policy configurations for an API using a policy template, you need to apply the template (containing a set of policies), and then configure the properties of the individual policies to suit the runtime requirements for that API.

    To apply a policy template on the API details page

    1. Click APIs in the title navigation bar.
      A list of all registered APIs appears.

    2. Select the required API.

    3. Click Edit.

    4. Click the Policies tab.
      The API’s policy information is provided in the following sections:

      • Policy stages - Threat Protection, Transport, Identify and Access, Request Processing, Routing, Traffic Monitoring, Response Processing, Error Handling

      • Infographic - List of applied policies

      • Policy properties - Collection of policy properties

    5. Click Apply template located in the lower right-corner of the Infographic section.
      This opens the Apply template dialog box.

    6. In the Template chooser, select one or more policy templates that you want to apply to the API.
      You can choose to display the details of an individual policy template by clicking the Info icon. This option populates the list of policies that are defined in the particular template.

    7. Select one or more policy templates that you want API Gateway to execute at run-time.

    8. Click Next. You must have at least one template selected to use the Next button.

    9. In the Apply Templates to API wizard, review the list of policies and the configuration details of the associated policies.

      • If necessary, you can click Previous to return to the Template chooser wizard and change your template selections.
      • If at any time you wish to abandon all your changes and return to the Policies tab, click Cancel.

    10. Click Apply.

      If you have one or more policy conflicts, API Gateway displays the conflicting/incompatible policies with a Conflict icon. You can choose to resolve the policy conflicts and do a Apply, or simply continue to Apply with conflicts.

      If you choose the continue with conflicts, API Gateway sets the focus on the conflicting policies with Conflict icon displayed next to the policy names in the Infographic section and the corresponding policy stages.

      API Gateway redirects you to the Policies tab. The newly applied policy template comprising a set of policies and the policy properties is displayed in the Infographic section.

    11. After you apply the required policy templates, click Save to save the updated API.

    Post-requisites: Activate the API when you are ready to put it into effect.

    Modifying a Policy Template on the API Details Page

    You must have the API Gateway’s manage policy templates functional privilege assigned.

    The Policies tab on the API details page specifies the set of policies that API Gateway executes when an application requests access to that particular API.

    The API can have a set of policies that are applied through a global policy, through a policy template, through a scope-level policy, and through API-level policies.

    To modify the details of a policy template on the API details page

    1. Click APIs in the title navigation bar.
      A list of all registered APIs appears.

    2. Select the required API.

    3. Click Edit.
      If the API is active, API Gateway displays a warning message to let you know that the API is active.

    4. Click the Policies tab.
      The API’s policy information is provided in the following sections:

      • Policy catalog - Threat Protection, Transport, Identify and Access, Request Processing, Routing, Traffic Monitoring, Response Processing, Error Handling

      • Infographic - List of applied policies

      • Policy properties - Collection of policy properties

    5. In the Infographic section, do the following for each policy in the list:

      a. Select the policy whose properties you want to examine or set.

      b. In the Policy properties section, set the properties as necessary.

      Note: Required properties are marked with an asterisk.

      c. Use the Delete (X) icon in any individual policy to remove that particular policy from the Infographic section.

    6. Click Open in full-screen to view policy properties in full screen mode.
      The Open in full-screen button is located in the upper right-hand corner of the Policy Configuration tab.

    7. Set the properties of the displayed policy, and then click OK.
      To exit full screen mode, click the Minimize icon.

    8. Click Save to save the updated API.
      Activate the API, if it is not active, to put it into effect.

    Saving Policy Definition of an API as Policy Template

    You must have the API Gateway’s manage policy templates functional privilege assigned.

    The Policies tab on the API details page specifies the set of policies that API Gateway executes when an application requests access to that particular API.

    The API can have a set of policies that are applied through a global policy, through a policy template, through a scope-level policy, and through API-level policies.

    You can save the current policy definition of an API as a new policy template. At a later time, you can reuse this policy template in other APIs. For more information, see Applying a Policy Template on the API Details Page.

    To save policy definition as policy template

    1. Click APIs in the title navigation bar.
      A list of all registered APIs appears.

    2. Select the required API.

    3. Click the Policies tab.
      The API’s policy information is provided in the following sections:

      • Policy catalog - Threat Protection, Transport, Identify and Access, Request Processing, Routing, Traffic Monitoring, Response Processing, Error Handling

      • Infographic - List of applied policies

      • Policy properties - Collection of policy properties

    4. Click Save as template located in the lower right-hand corner of the Infographic section.

    5. In the Save as template dialog box, provide the required information for each of the displayed data fields:

      Field Description
      Name Name of the policy template.
      Description Description of the policy template.
    6. Click Save.

    Supported Alias and Policy Combinations

    API Gateway provides a set of aliases whose runtime-specific environment variables can be used in configuring the policy routing endpoints, routing rules, endpoint connection properties, and outbound authentication tokens. The types of aliases whose properties you can use for the policy configurations are:

    Not all policies support the full set of aliases that are available in API Gateway. Some aliases are applicable only with certain policies and for certain policy parameters. For example, a Simple alias applies to the routing and traffic monitoring policies, whereas an Endpoint alias applies only to the routing policies. When you define a Straight Through Routing policy with a simple alias, the alias property is defined using the Endpoint URI field. When you define the same Straight Through Routing policy with an endpoint alias, the alias property is defined using a set of fields - Endpoint URI, SOAP Optimization Method, HTTP Connection Timeout, Read Timeout, Pass WS-Security Headers, and Keystore Alias.

    The following table identifies the policies and policy parameters that each alias type supports:

    Simple Alias

    Policy Name Policy Parameter Name
    Straight Through Routing In the Straight Through Routing definition:

    • Endpoint URI
    Content-based Routing In the default and custom Route To rule definitions:

    • Endpoint URI
    Conditional Routing In the default and custom Route To rule definitions:

    • Endpoint URI
    Load Balancer Routing In the Route To rule definition:

    • Endpoint URI
    Dynamic Routing In the default and custom Route To rule definitions:

    • Endpoint URI
    Log Invocation In the Email Destination section:

    • Email Address
    Monitor Performance In the Email Destination section:

    • Email Address
    Monitor SLA In the Email Destination section:

    • Email Address
    Traffic Optimization In the Email Destination section:

    • Email Address

    Endpoint Alias

    Policy Name Policy Parameter Name
    Straight Through Routing In the Straight Through Routing definition:

    • Endpoint URI
    • SOAP Optimization Method (Applicable only for SOAP APIs)
    • HTTP Connection Timeout
    • Read Timeout
    • Pass WS-Security Headers (Applicable only for SOAP APIs)
    • Keystore Alias
    • Key Alias
    Content-based Routing In the default and custom Route To rule definitions:

    • Endpoint URI
    • SOAP Optimization Method (Applicable only for SOAP APIs)
    • HTTP Connection Timeout
    • Read Timeout
    • Pass WS-Security Headers (Applicable only for SOAP APIs)
    • Keystore Alias
    • Key Alias
    Conditional Routing In the default and custom Route To rule definitions:

    • Endpoint URI
    • SOAP Optimization Method (Applicable only for SOAP APIs)
    • HTTP Connection Timeout
    • Read Timeout
    • Pass WS-Security Headers (Applicable only for SOAP APIs)
    • Keystore Alias
    • Key Alias
    Load Balancer Routing In the Route To rule definition:

    • Endpoint URI
    • SOAP Optimization Method (Applicable only for SOAP APIs)
    • HTTP Connection Timeout
    • Read Timeout
    • Pass WS-Security Headers (Applicable only for SOAP APIs)
    • Keystore Alias
    • Key Alias
    Dynamic Routing In the default and custom Route To rule definitions:

    • Endpoint URI
    • SOAP Optimization Method (Applicable only for SOAP APIs)
    • HTTP Connection Timeout
    • Read Timeout
    • Pass WS-Security Headers (Applicable only for SOAP APIs)
    • Keystore Alias
    • Key Alias

    HTTP Transport Security Alias

    Policy Name Policy Parameter Name
    Outbound Authentication - Transport In the Authentication scheme:

    • Alias

    SOAP Message Security Alias (Applicable only for SOAP APIs)

    Policy Name Policy Parameter Name
    Outbound Authentication - Message In the Authentication scheme:

    • Alias

    webMethods IS Service Alias

    Policy Name Policy Parameter Name
    Invoke webMethods IS (Request Processing) webMethods IS Service Alias
    Invoke webMethods IS (Response Processing) webMethods IS Service Alias

    XSLT Transformation Alias

    Policy Name Policy Parameter Name
    Request Transformation (Request Processing) Transformation Configuration
    • Payload Transformation
      • XSLT Transformation alias
    Response Transformation (Response Processing) Transformation Configuration
    • Payload Transformation
      • XSLT Transformation alias