Implement APIs

API Implementation

After you create an API, it is time to start defining the behavior of the API.

Some of the important considerations that you take into account when you define your API’s behavior are:

API Gateway UI provides a visual guided experience for designing, developing, and testing APIs. The API caching, filtering, and sorting capability helps in retrieving your APIs faster. You can use the pagination function to determine how much data must be displayed and at what frequency. These features ensure minimum processing and good response time.

API Gateway provides various policies that are designed to let you add management capabilities, to an API or to all APIs at a global level, easily. You can enforce these policies on an API to secure, limit, and route requests sent to APIs.

The API testing capability allows you to test your APIs before you publish them onto a portal for consumption. API Gateway also provides the API mocking capability that enables you to simulate the behavior of a real API for testing the API.

API Gateway provides logging and monitoring capabilities that help debug your APIs so that locating the root cause of the issue based on what is observed is easy. In addition, you can monitor API usage to understand API trends.

The following sections describe the various ways in which you can implement your APIs such as, API mocking, enforcing different types of policies as required, creating and managing applications and aliases, creating API mashup, and so on.

API Mocking

Using API Gateway, you can mock an API by simulating the native API. For example, if you have an API without a native implementation, you can mock that API. The mocked response is returned to the consumer when the API is invoked.

In API Gateway, when you enable mocking for an API, a default mock response is configured for each combination of resource, operation, status code, and content-type based on the example and schema specified in that API. You can add a condition to the operation in the resource.

Note
  • You cannot enable or disable mocking for an active API.
  • API Gateway does not support API Mocking for GraphQL API.

As an API Provider, you can create or modify the default mock response. You can specify conditions and associate an IS service with the mocked API. When an IS service is associated with a mocked API, the associated IS service must adhere to the apigateway.specifications:mockService specification.

At runtime, when the mocked API is invoked, instead of calling the native API, API Gateway returns the mocked response to the consumer based on the following priorities:

  1. If any of the conditions for the invoked operation satisfies, API Gateway returns the associated mocked response.

  2. If any of the conditions for the invoked operation is not satisfied, and if an IS service is configured for the API, then API Gateway invokes the IS service and returns the IS service response.

  3. If any of the conditions for the invoked operation is not satisfied, and if an IS service is not configured for the API, then API Gateway returns the default mocked response.

API mocking is supported only for SOAP and REST APIs.

Note
You must have the API Gateway’s manage APIs or activate/deactivate APIs functional privilege assigned to perform API mocking.

Enabling API Mocking

You can enable or disable API mocking through the API details page.

Note
You cannot enable or disable API mocking for active APIs.

To enable API mocking

  1. Click APIs in the title navigation bar.

  2. Select the required API from the list of available APIs.
    The API details page for the selected API appears.

  3. Click icon and select Enable mocking.
    This generates the default mock responses.

Modifying API Mocking Details

You must select Enable mocking from the API details page.

You can modify API mocking details, as required, from the API details page.

To modify API mocking details

  1. Click APIs in the title navigation bar.
    A list of all registered APIs appears.

  2. Click the required API. The API details page appears.

  3. Click Edit.

  4. Click API mocking.

  5. Specify the following information in the IS service section:

    Field Description
    Invoke service Specifies the webMethods Integration Server service to be invoked.
    Run as user Type the user name you want API Gateway to use to invoke the IS service.
  6. Select the operation that you want to modify from the Mocked responses section.

  7. Click Add Response if you want to add a response and select the status code from the drop-down.

  8. Click icon.
    This adds the status code created to the existing status code list.

  9. Select the status code you want to modify.

  10. Click + Add Response Header and provide the following information to add the required response headers:

    Field Description
    Header key Specify the HTTP header key that would be contained in the header of HTTP response.
    Header value Specify the HTTP header value that would be contained in the header of HTTP response.

    You can add more response headers by clicking icon.

  11. Click + Add Content-type to add a content-type to the status code selected and provide the following information:

    Field Description
    Content type Select the content-type to be added to the selected status code from the drop-down list.
    Mock payloads Specify a mock response payload for the content-type selected.

    You can add more content-types by clicking Add.

  12. Click + Add Conditions to add a condition to the operation in the resource:

    Field Description
    Condition name Specify the name for the condition.
    Condition parameter Select the type to which the condition is to be applied. The available options are:

    • Body

    • Header

    • Query parameter (Applicable only for REST APIs)
    Key The key can be a string for the header and query parameter and for body it can be a JSON path or an XML path.
    Value The value of the condition. Additionally, you can type an * (asterisk) to ignore the value specified in this parameter and the condition is satisfied based on the value specified in the Key parameter.
    Status code Select the status code from the drop-down list.

    Note:

    • You must enable the property Send native provider fault in the Administration > General > API fault section in order to have correct mock response for status code 506.

    • While invoking an API remember to use the query parameter expectedStatusCode in order to have correct mock responses for status codes 100 and 202.
    + Add Response Header Add a response header to the resource selected by providing the following information:

    • Header key. Specify the HTTP header key that would be contained in the header of HTTP response

    • Header value. Specify the HTTP header value that would be contained in the header of HTTP response.
    + Add Content-type Add a content-type to the status code selected by providing the following information:

    • Content type. Select the content-type to be added to the selected status code from the drop-down list.

    • Mock payload. Specify a mock response payload for the content-type selected.

    You can add more conditions by clicking Add.

  13. Click Save.

Custom Replacer

API Gateway allows you to send a dynamic custom response instead of a static mocked response to the consumer when the mocked API is invoked. In the mocked response, you can specify multiple custom replacers. Custom replacer is used to replace the custom variables with the values defined in the request headers, query parameters, and request body. The custom replacer is available in the ${request.<ConditionParameter>.<Key|JsonPath|XPath>} format. The custom replacers are:

Consumer Applications

An application defines the precise identifiers by which messages from a particular application is recognized at run time. The identifiers can be, for example, user name in HTTP headers, a range of IP addresses, such that API Gateway can identify or authenticate the applications that are requesting an API.

The ability of API Gateway to relate a message to a specific application enables it to:

An application has the following attributes for specifying the identifiers:

You can configure various authentication strategies to authenticate an incoming request to the application. You can create multiple strategies authorized by an API for an application. These strategies provide multiple authentication mechanisms or multiple authorization servers for a single authentication scheme. For example, in case of OAuth authentication scheme, you want the application to support both OKTA and PINGFederate or OKTA with multiple tenants. This can be configured as OAuth strategy for the application.

If you have the Manage Application functional privilege assigned, you can create and manage applications, and register applications with the APIs.

These are the high level stages of managing and using an application:

  1. API developers request the API Gateway administrators to create an application for access as per the required identification criteria.

  2. API Gateway provider or administrator validates the request and creates a new application, there by provisioning the application specific access tokens (API access key and OAuth credentials).

  3. API Developer, upon finding a suitable API, sends a request to API Gateway for consumption by providing the application details.

  4. After validating the request, API Gateway provider or administrator associates the application with the API. Keys are generated for applications and not for every API that the application consumes.

    Note
    The approval process, if any, is handled by the requesting application and not handled by API Gateway.
  5. The API developer can then use the application with the proper identifier (such as the access key or identifier) to access the API.

API key expiration date

An API Gateway application has an optional expiration date for its API key. When the API access key expires, the application cannot be identified. The API Gateway Administrator can configure the apiKeyExpirationPeriod parameter from the General > Extended settings page. If the expiration date is not specified, then the API key never expires.

Suspended Applications

You can suspend applications so as to disable the identification of requests temporarily. If a suspended application is identified while processing a request the request is rejected with HTTP 403 (Forbidden) error. The response body has the following content:


Application has been identified but it is currently suspended. Please contact
the API Gateway administrator for further details.    

You can resume the suspended applications to enable the identification again.

Creating an Application

You must have the API Gateway’s manage applications functional privilege assigned to perform this task.

To create an application

  1. Click Applications in the title navigation bar.

  2. Click Create application.

  3. Provide the following information in the Basic information section:

    Field Description
    Name Type a name for the application.
    Version Version of the application. By default it is 1.0 but can be modified to a required value.
    Owner Name of the team who owns the application.
    The application owner can view all details of the application including the API access key. If you specify a team as application owner, then all members of the team can view the API access key.
    Note: You cannot modify ownership details of the applications you create through Developer Portal.
    Description Type a description of the application.
    Requestor comment Specify your comments, if any.
    This field is visible only when the approval configuration for Create application is enabled in the Administration > General > Approval Configuration > Create application section.

    The pending requests for an application can be approved by one of the following:

    • List of users and user groups of the teams that the application is associated with. You must specify the required users and user groups in the Approvers section of the Basic information tab when creating or editing the corresponding team.
    • List of users and user groups of the teams that the application is associated with. You must specify the required users and user groups in the Team Administrators section of the Basic information tab when creating or editing the corresponding. This is applicable only if the Include team administrators as approvers option is selected.

    For information on options that can be configured for a team, see Creating Teams.

  4. Click Continue to Identifiers.
    Alternatively, you can click Identifiers in the left navigation panel.
    You can save the application by clicking Save at this stage and add the Identifiers and APIs at a later time.

  5. Provide the following information in the Identifiers section:

    Field Description
    IP address range Provide the IP address range or range of trusted IPv4 or IPv6 addresses that identify requests from a particular application.

    You can add more range options by clicking +Add and adding the required information.
    Partner identifier Specifies the third-party partner’s identity.
    Client certificates Click Browse and select the client certificate or certificate chain to be uploaded. The client certificate specifies the X.509 certificates that requests from a particular application.

    Note: API Gateway supports .cer and .pem certificates for identifying consumer applications.

    You can add multiple certificates by clicking +Add
    Claims Provide a set of claims for the JWT and OpenID clients.

    A claim is a unique identifying information that identify requests from a particular consumer application. The claim set is identified by a unique Name and is defined as a name-value pair that consists of a Claim name and a Claim value.

    You can add more claims and claims sets by clicking +Add and adding the required information.
    Header key Specify the HTTP header key to identify the requests from an application.
    Header value Specify the HTTP header value to identify the requests from an application.
    You can add multiple header key and value by clicking +Add.
    Other identifiers Select one of the options to identify requests from a particular application and provide the required value:
    • Hostname. Specify the host name.
    • Token. The token that is required to identify requests from an application.
    • Username. The username credential to identify requests from an application.
    • WS-Security username. The WSS username to identify requests from an application.
    • Payload identifier. The payload identifier that is required to identify requests from an application.
  6. Click Continue to APIs >.
    Alternatively you can click APIs in the left navigation panel.
    You can save the application by clicking Save at this stage and add the APIs at a later time.

  7. Type a keyword to find the required API and click + to add the API.
    Adding an API to the application enables the application to access the API. An API developer while invoking the API at runtime, has to provide the access token or identification token for API Gateway to identify the application.

  8. Type the required Requestor comment.

  9. Click Continue to Advanced >
    Alternatively you can click Advanced in the left navigation panel.
    You can save the application by clicking Save at this stage and add the APIs at a later time.

  10. Specify the origin from which the responses originating are allowed during response processing for the application.

  11. Click +Add to add the origin.
    You can add multiple origins using icon.

  12. Click Continue to Authentication >
    Alternatively you can click Authentication in the left navigation panel.
    You can save the application by clicking Save at this stage and add the Authentication strategy at a later time.

  13. Click Create strategy.
    A strategy is a way to authenticate the incoming request and provides multiple authentication mechanisms or multiple authorization servers for a single authentication scheme. You can create multiple strategies authorized by an API for an application.

  14. Select one of the Authentication schemes:

    • OAUTH2. Provide the following information:

      Field Description
      Name Provide the name for the strategy.
      Description Provide a description to describe the strategy.
      Authentication server Specify the authentication server.

      The available values are local, which is the default server or any other configured external authorization server.
      Audience Provide a value or URI, the intended recipient of the authorization server scope.
      The application that receives the token verifies that the audience value is correct and rejects any tokens intended for a different audience.
      Generate Credentials Enable the toggle button to generate the client dynamically in the authorization server and provide the following information:

      • Type. Select one of the client types:
        • Confidential. A confidential client is an application that is capable of keeping a client password confidential to the world. This client password is assigned to the client app by the authorization server. This password is used to identify the client to the authorization server, to avoid fraud. An example of a confidential client could be a web app, where no one but the administrator can get access to the server, and see the client password.
        • Public. A public client is an application that is not capable of keeping a client password confidential. For instance, a mobile phone application or a desktop application that has the client password embedded inside it. Such an application could get cracked, and this could reveal the password. The same is true for a JavaScript application running in the users browser. The user could use a JavaScript debugger to look into the application, and see the client password.

      • Application type. Specify the application type.
        • WEB. A web application is an application running on a web server. In reality, a web application typically consists of both a browser part and a server part. The client password could be stored on the server. The password would thus be confidential.
        • USER_AGENT. A user agent application is for instance a JavaScript application running in a browser. The browser is the user agent. A user agent application may be stored on a web server, but the application is only running in the user agent once downloaded.
        • NATIVE. A native application is for instance a desktop application or a mobile phone application. Native applications are typically installed on the users computer or device (phone, tablet etc.). Thus, the client password will be stored on the users computer or device too.

      • Token lifetime. Specify the token lifetime in seconds for which the token is active.

      • Token refresh limit. Specify the number of times you can use the refresh token to get a new access token.

      • Redirect URIs. Specify the URIs that the authorization server can use to redirect the resource owner’s browser during the grant process. You can add multiple URIs by clicking +Add.

      • Grant type. Specify the grant type to be used to generate the credentials. Available options can be authorization_code, passeord, client_credentials, refresh_token, and implicit which are dynamically populated from the authorization server. For example, if the authorization server does not support client credentials, the option is not available in the options list.

      • Scopes. Select the scopes that are to mapped for the authentication strategy.

      • Note: in API Gateway 10.2, the scopes are automatically created when you associate an API to an application. From API Gateway 10.3 onwards you have to select scopes from the authorization server that have to be associated with the strategy.
      Client id Specify the Client identifier for a client application available in the authorization server that identifies the client application in the authorization server to map the client to the API Gateway application.
      This is required if you have a client application available in the authorization server and do not want to dynamically create a client.
    • JWT. Provide the following information:

      Field Description
      Name Provide the name for the strategy.
      Description Provide a description to describe the strategy.
      Authentication server Specify the authentication server.

      The possible values are local, which is the default server or any other configured external authorization server.
      Audience Provide a value or URI, the intended recipient of the authorization server scope.
      The application that receives the token verifies that the audience value is correct and rejects any tokens intended for a different audience.
      HMAC algorithm Select if the authorization server is returning a JWT with HMAC algorithm and provide the shared secret value to validate the JWT.
    • OPENID. Provide the following information:

      Field Description
      Name Provide the name for the strategy.
      Description Provide a description to describe the strategy.
      Authentication server Specify the authentication server.

      The available values are local, which is the default server or any other configured external authorization server.
      Audience Provide a value or URI, the intended recipient of the authorization server scope.
      The application that receives the token verifies that the audience value is correct and rejects any tokens intended for a different audience.
      Generate Credentials Enable the toggle button to generate the credentials required to identify the client application and provide the following information:

      • Type. Select the client type, Public or Confidential.
        • Confidential. A confidential client is an application that is capable of keeping a client password confidential to the world. This client password is assigned to the client app by the authorization server. This password is used to identify the client to the authorization server, to avoid fraud. An example of a confidential client could be a web app, where no one but the administrator can get access to the server, and see the client password.
        • Public. A public client is an application that is not capable of keeping a client password confidential. For instance, a mobile phone application or a desktop application that has the client password embedded inside it. Such an application could get cracked, and this could reveal the password. The same is true for a JavaScript application running in the users browser. The user could use a JavaScript debugger to look into the application, and see the client password.

      • Application type. Specify the application type.
        • WEB. A web application is an application running on a web server. In reality, a web application typically consists of both a browser part and a server part. The client password could be stored on the server. The password would thus be confidential.
        • USER_AGENT. A user agent application is for instance a JavaScript application running in a browser. The browser is the user agent. A user agent application may be stored on a web server, but the application is only running in the user agent once downloaded.
        • NATIVE. A native application is for instance a desktop application or a mobile phone application. Native applications are typically installed on the users computer or device (phone, tablet etc.). Thus, the client password will be stored on the users computer or device too.

      • Token lifetime. Specify the token lifetime in seconds for which the token is active.

      • Token refresh limit. Specify the time in seconds for which the token refresh is applicable.

      • Redirect URIs. Specify the URIs that the authorization server can use to redirect the resource owner’s browser during the grant process. You can add multiple URIs by clicking +Add.

      • Grant type. Specify the grant type to be used to generate the credentials. Available options are Authorization code, Implicit, Resource owner, Client credentials.

      • Scopes. Select the scopes that are to be associated to the generated client.

      • Note: in API Gateway 10.2, the scopes are automatically created when you associate an API to an application. From API Gateway 10.3 onwards you have to select scopes from the authorization server that have to be associated with the strategy.
      Client id Specify the Client identifier that identifies the client application in the authorization server to map the client to the API Gateway application.
      This is required if you do not choose to generate credentials to identify the client application.
  15. Click Add.
    The strategy is configured and listed in the Strategies table.

    Note
    API Gateway allows you to generate a new Client ID and Client Secret for an existing strategy. However, once the credentials are generated for a strategy, it can no longer be removed. The Generate credentials toggle is disabled in the UI when you update a strategy.
  16. Click Save.
    The application is created and listed in the list of applications in the Manage applications page, once approved.

Viewing List of Applications and Subscriptions

You can view the list of applications in the Manage applications page from where you can create, delete, and select an application to view its details.

To view the application list and application and subscription details

  1. Click Applications in the title navigation bar.
    A list of all registered applications and subscriptions appear.

    • denotes application.
    • denotes subscription.

  2. Select an application.

    The application details page displays the following information: basic information that contains details such as name, description, owner, and creation time, identifiers, access tokens, APIs registered for the application, advanced configurations, and authentication strategies configured for the application.

    Application credentials, such as, API Keys or OAuth client secrets are visible only to the application owner. All other users can only see an encrypted value. Since Developer Portal and API Gateway do not support a central user management, API Gateway users cannot see the application credentials of the application requested through Developer Portal.

  3. Select a subscription.

    You can view the applications and the associated package, plan, used quota, start time, end time, and the remaining period of the subscription.

    Note
    You cannot create a subscription from this page. To create a subscription, use the subscription API. For details about creating subscriptions using a REST API, see Subscription Management.
    You can also create a subscription from the Developer Portal.

Regenerating API Access Key

You must have the API Gateway’s Manage applications functional privilege assigned to perform this task.

You can regenerate an API access key in the application details page from where you can view application details.

To regenerate an API key

  1. Click Applications in the title navigation bar.
    A list of all registered applications is displayed.

  2. Select an application.
    The application details page displays the basic information, identifiers, access tokens, API key, APIs registered and strategies configured for that application.

  3. Click icon.
    The API access key is regenerated and the new API access key appears in the API access key field.

Modifying Application Details

You can modify the details of an application as required from the application details page.

To modify application details

  1. Click Applications in the title navigation bar.
    A list of registered applications is displayed.

  2. Select an application.

  3. Click Edit in the application details page.

  4. Modify the required fields in the Basic information section.
    Note: You cannot modify ownership details of the applications you create through Developer Portal.

  5. Click Identifiers.

  6. Modify the required fields in the Identifiers section.

  7. Click APIs.

  8. Add or delete the APIs that are registered.

  9. Modify the strategies or create a new strategy.

  10. Modify the required values.

  11. Click Save.

Registering an API with Consumer Applications from API Details Page

Consumer applications created in API Gateway can be associated with APIs from the API details page.

To register APIs with consumer applications

  1. Click APIs in the title navigation bar.
    A list of APIs is displayed.

  2. Select an API.

  3. Click Edit in the API details page.

  4. Click Application tab in the API details page.

  5. Type characters in the search field and click the Search icon.
    This field displays the only list of applications that are assigned to the teams that you are a part of.

  6. Select the required applications and click +.
    You can add more applications in a similar way.

  7. Click Save.

Suspending an Application

You must have the API Gateway’s Manage applications functional privilege assigned or you must be the owner of the application to perform this task.

To suspend an application

  1. Click Applications in the title navigation bar.
    A list of all the available applications are displayed.

  2. Click the toggle button icon (Active state), in the action column for the respective application, to suspend the application.
    Alternatively, you can click Suspend in the application details page.

  3. Click Yes in the confirmation dialog box.
    The application is suspended. The toggle button in the Applications page changes to icon (suspended state) and the option in the application details page changes to Suspend.

Activating a Suspending Application

You must have the API Gateway’s Manage applications functional privilege assigned or you must be the owner of the application to perform this task.

You can activate a suspended application, from the application details page.

To activate a suspended application

  1. Click Applications in the title navigation bar.
    A list of all the available applications are displayed.

  2. Click the toggle button icon (suspended state), in the action column for the respective application, to activate the application.
    Alternatively, you can click Activate in the application details page.

  3. Click Yes in the confirmation dialog box.
    The application resumes. The toggle button in the Applications page changes to icon (active state) and the option in the application details page changes to Suspend.

Policies

API Gateway provides a policy framework that enables you to program API behavior and implements specific limited management functions without writing any code. You can enforce a policy 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 runtime. For example, a policy could instruct API Gateway to perform any of the following tasks and prevent malicious attacks:

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

How does policy enforcement work?

When 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.

For example, consider an API is enforced with the identify and access policy at the following policy enforcement levels: global, API-level, and scope-level. The precedence of the policy enforcement that is effective for the API at runtime 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 access policy applied through both globally and at the API-level, API Gateway does not show conflict. The Identify and access policy applied through the global policy takes precedence and is processed at runtime.

Similarly for a REST API, Identify and access policy is applied through a scope-level policy at the resource level and also at the API level, the Identify and access policy applied through the scope-level policy takes precedence and is processed at runtime.

When you apply a transport policy at the global level, the transport policy applied at the API level is in the disabled state. When you try deleting the API-level transport policy that is in the disabled state, an error displays and you are not allowed to delete this policy as the API-level transport policy is required and gets enforced when you deactivate the global policy.

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. For details about the variable syntaxes to use, see Variable Framework.

Aliases

API Gateway provides the capability of using aliases. An alias holds stage-specific property values that can be be shared by multiple policy configurations. Aliases referenced by policy configurations are substituted during runtime. Changing an alias value affects all referencing policies. Aliases are referenced through a name, therefore, alias names have to be unique within an API Gateway. The corresponding alias value is substituted in place of an alias name during run-time. Thus the same alias can be referred to in multiple policies and the change in a particular alias would affect all the policy properties. For more details about aliases and how to use them, see Aliases.

Policy templates

API Gateway provides policy templates, which are a set of policies that can be associated directly with an individual API. Policy templates provide the flexibility to alter the policy’s configurations to suit the individual API requirements. These policy templates apply at the API level, and can be customized to suit the needs of a particular API. For more details about policy templates and how to use them, see Policy Templates.

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. For details about policy validation and dependencies, see Policy Validation and Dependencies.

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 Bulkhead

Bulkhead configuration allows you to specify the maximum number of concurrent requests processed by an API. You can configure this setting individually for an API or globally for all APIs.

When the number of concurrent requests to an API exceeds the specified limit, the excess requests are rejected. In such scenarios, the policy violation events are generated to report the violations occurred for an API. If there are 100 violations, then 100 policy violation events are generated.

As per the order of policies, the Bulkhead limit policy is applied first. That is, if you have applied multiple policies including the Bulkhead limit policy, then the Bulkhead limit policy is applied first.

Why do we configure bulkhead limit for APIs?

In an environment where multiple APIs are running, there are chances of one API making maximum use of the system resources due to the number of invocations. This in turn suppresses the performance of other APIs. Consider the following example. The maximum thread pool size of your system is 100, and it is shared among five APIs. When there are 100 invocations to one API, then that API uses up all the available threads to process its requests. The others APIs must wait till there are available threads.

To prevent this, you can specify the maximum number of concurrent requests that an API can process. This number depends on the maximum thread pool size of your system. Consider the same scenario after specifying the bulkhead limit for the APIs. In our example, the thread pool size is 100 and if you configure 20 as the maximum concurrent limit for each API, then each of the APIs can process a maximum of 20 requests, exceeding which the requests are rejected.

This ensures optimal usage of the system resources.

As part of bulkhead configuration, you can specify

Enabling bulkhead for APIs at the API-level

This use case explains how to configure the bulkhead limit for an API.

This use case starts when you have an API for which you have to enforce a bulkhead limit and ends when you have successfully applied the bulkhead limit to the API.

To enforce bulkhead limit to an API

  1. Click APIs in the title navigation bar.

  2. Select the required API.

  3. Click the Policies tab.

  4. From the Policy catalog section, expand Transport, and select Enable bulkhead.

  5. Provide the following values in the Policy properties section:

    Field Description
    Maximum concurrent calls Specify the maximum number of concurrent requests that the API can process, exceeding which the requests are rejected.
    Enable bulkhead for callbacks Select this option to specify the maximum number of concurrent callbacks for the API. If you select this, the Maximum concurrent callbacks field appears.
    Note: This setting is applicable only for REST APIs. Hence, this field is not displayed when you perform the bulkhead limit configuration for any other APIs.
    Maximum concurrent callbacks Specify the maximum number of concurrent callbacks that the API can process, exceeding which the callbacks are rejected. This field appears only when you have selected the Enable bulkhead for callbacks check box.
    Add Retry-After response header Select this option to include the Retry-after header in the response sent to the client when requests are rejected. This is to keep the client informed about the waiting duration before sending any consecutive requests.
    Note: This option is to provide an approximate waiting duration before sending any consecutive requests; and it does not guarantee that the requests sent after the specified time are processed. The maximum number of concurrent requests that are processed is purely dependant on the configured bulkhead limit.
    Retry after (value, in seconds) Specify the duration that the client must wait, after requests are rejected by API Gateway, to send consecutive requests.
    This field appears only when you have selected the Retry after (value, in seconds) check box.
  6. Click Save.

    The bulkhead limit is applied to the API.

Bulkhead feature considerations

This section lists the impact of the bulkhead policy on other features that you must remember when using the policy:

Applicable API types

Bulkhead policy is applicable for REST, SOAP, OData, and GraphQL APIs.

However, you can specify the number of maximum concurrent callbacks only for the REST APIs.

Bulkhead limit configuration for APIs in a mashup

API-level bulkhead limit is not applied to the participating APIs. Instead, the bulkhead limit configured at the mashup API-level takes effect.

Bulkhead limit configured for APIs in cluster

In cluster environments, you can specify the bulkhead limit in each node. API Gateway checks the number of concurrent requests per instance and allows or rejects the requests based on the bulkhead limit configured for an API in the corresponding node.

Overall thread pool violation

When you enable the Bulkhead policy and if the overall thread pool is violated, then the requests exceeding the thread pool count are all rejected, and the Connection timeout message is displayed.

Conditional Routing policy

When the Bulkhead policy is enabled with the Conditional Routing policy, then bulkhead limit configured at API-level for the participating APIs is applicable.

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.
SOAP Version Validation Enabled For SOAP-based APIs.

Specifies whether API Gateway should only accept the request that includes the specified SOAP version.

If this option is selected, it is set as true and API Gateway accepts only the requests that include the specified SOAP version.

The non-selected protocol is rejected with an error.

If this option is not selected, it is set as false and API Gateway accepts both the SOAP versions.

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.

Custom Extension policies allow you to handle requirements that might not be provided by the out-of-the-box policies. You can add these custom extensions into API Gateway policy stages. To learn more about Custom Extension, see Custom Policy Extension.

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.
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.
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. This is not applicable to a GraphQL API. 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.

OAuth, JWT, and OpenID Configuration

This section describes the Open Authorization (OAuth), JSON Web Token (JWT), and OpenID Connect (OpenID) authentication protocols that you can use to identify and authorize a client application. The application is first identified based on the criteria provided in the strategy configured. A strategy is a way to authenticate the incoming request and provides multiple authentication mechanisms or multiple authorization servers for a single authentication scheme. API Gateway identifies the application and validates the token submitted through the strategy configured in the application.

OAuth Authentication Use Case and Workflow

The Open Authorization is a flexible authorization framework for securing application access to protected resources of APIs. OAuth 2.0 uses access tokens that are presented by client applications (on behalf of the end users) to access the protected resources.

The OAuth authorization framework includes the following terms:

Roles

Authorization Grant Types

Clients

API Gateway can be used as an authorization server and as a resource server.

API Gateway as a Resource Server

When API Gateway acts as a resource server, it hosts the protected resources, and accepts and responds to the client applications’ requests that include an access token. The client application sends the access token in the Authorization request header field using the Bearer authentication scheme. The resource server validates the access token locally or remotely if it cannot validate locally.

If the token is valid and the client application has privileges to access the protected resources, the resource server executes the request. If the access token is invalid, it rejects the request.

API Gateway as an Authorization Server

When API Gateway acts as an authorization server, it receives authorization requests from client applications. The authorization server handles the interactions between the client application, resource server, and resource owner for approval of the request.

As an authorization server API Gateway issues tokens to client applications on behalf of a resource owner for use in authenticating subsequent API calls to the resource server. The resource server hosts the protected resources, and can accept or respond to the protected resource requests using access tokens. If the client application is authorized to access the protected resources, the resource server executes the request. The authorization server retains the information about the access tokens it issues, including the user information. When a client presents an access token to the resource server, the resource server sends the token to the authorization server to ensure that the token is valid and that the requested service is within the scope for which the access token was issued. A scope is the definition of the resources that the client application can access on behalf of a resource owner. If the client application does not have privileges to access the resources, the resource server rejects the request.

Using API Gateway with an External Authorization Server

When API Gateway is the resource server, you must specify an authorization server. As an alternative to using API Gateway as the authorization server, you can use a third-party server as the authorization server. This allows API Gateway to validate access tokens issued by third-party servers and also allow to dynamically create clients in the third-party server.

Note
Before you configure API Gateway to use a third-party authorization server, make sure that the authorization server is compliant with the RFC 7662, OAuth 2.0 token introspection.
From API Gateway release 10.3 onwards API Gateway supports multiple authorization servers.

To use an external authorization server, you must configure your third-party authorization server. This includes, but is not limited to, the following:

Currently, API Gateway, by default, can be used with the following third-party authorization servers, but are not limited to, that are RFC 7662, OAuth 2.0 token introspection compliant:

You can also use other third-party authorization servers like Google, keycloak, and so on.

Authorizations for applications created from Developer Portal

When you create applications through Developer Portal, you must specify the required authorization server using the watt.server.oauth.authServer.alias settings in the Administration section of API Gateway.

If API Gateway is the authorization server, then provide local as the value of the watt.server.oauth.authServer.alias setting. Else, provide the name of the corresponding authorization server. For information on extended settings, see Configuring Extended Settings.

Use case 1: OAuth Authentication with API Gateway as a Resource server as well as an Authorization server

This describes the high level workflow for the scenario where API Gateway is a resource server as well as an Authorization server.

  1. Configure API Gateway as an internal authorization server. Ensure you configure OAuth scopes while configuring the authorization server. For a complete procedure on configuring API Gateway as an internal authorization server, see Configuring the Internal Authorization Server.

  2. Map the scopes.
    For a complete procedure on mapping scopes, see Mapping OAuth or OpenID Scopes.

  3. Enforce the Identify and authorize application policy on the API.
    Ensure to select OAuth2 token. For details of the Identify and authorize application policy see, Identify and Authorize Application.

  4. Associate an application with the API.
    You can create a new application or use an existing one. Ensure that the application associated contains the strategy for OAuth authentication. While creating a strategy you can associate it with the scopes that are available to be used while using dynamic client registration. For a complete procedure on creating an application with a strategy, see Creating an Application. See Authorizations for applications created from Developer Portal for information on configuring authorization server for the applications created from Developer Portal.

  5. Activate the API.
    User on invoking the API uses the OAuth identification method to access the protected resource.

  6. Get access token through the following URLS:

    invoke/pub.apigateway.oauth2/authorize

    invoke/pub.apigateway.oauth2/getAccessToken

  7. Use the access token to invoke the API.

Use case 2: Oauth Authentication with API Gateway as a Resource server and an external Authorization server

This describes the high level workflow for the scenario where API Gateway is the resource server with a third-party authorization server. This is generally used in an environment where there is an existing authorization server, which is used with API Gateway as a resource server.

  1. Configure a Provider if you are using the Dynamic client registration. Else you can proceed to step 2.
    For a complete procedure on configuring a provider, see Adding a Provider.

  2. Configure an external authorization server.
    Ensure you configure OAuth scopes while configuring the authorization server. For a complete procedure on configuring an external authorization server, see Adding an External Authorization Server.

  3. Map the scopes.
    For a complete procedure on mapping scopes, see Mapping OAuth or OpenID Scopes.

  4. Enforce the Identify and authorize application policy on the API.
    Ensure to select OAuth2 token. For details of the Identify and authorize application policy see, Identify and Authorize Application.

  5. Associate an application with the API.
    You can create a new application or use an existing one. Ensure that the associated application contains the strategy for OAuth authentication and contains the client ID. While creating a strategy you can associate it with the scopes that are available to be used while using dynamic client registration. If the authorization server supports dynamic client registration, then you can select the option Generate credentials. If the application is already created in authorization server, then provide the respective client id. For a complete procedure on creating an application with a strategy, see Creating an Application. See Authorizations for applications created from Developer Portal for information on configuring authorization server for the applications created from Developer Portal.

  6. Activate API.
    User on invoking the API uses the OAuth identification method to access the protected resource.

  7. Get the access token from the authorization server.

  8. Use the access token to invoke the API.

For a detailed procedure on using OAuth Authentication with API Gateway as a Resource server and OKTA as an external Authorization server, see Securing APIs using 3rd party OAuth 2 provider in API Gateway.

OAuth Authorization Workflow

The flow of authorization requests and responses between the end user, client application, authorization server, and resource server is as depicted in the following figure:

icon

The OAuth authorization workflow is as follows:

  1. The end user logs in, the client application sends the authentication request to the authorization server to obtain an access token.

  2. Authorization server validates the request and generates an access token for the client.

  3. Client uses this access token to send HTTP requests to API Gateway.

  4. API Gateway then performs the following:

    a. Identifies the application using the client ID.

    b. Validates the token locally or remotely if it is not possible locally.

    c. Checks if the requested resource is part of the scopes in the token.

    d. Checks the audience.

    If all the above are validated, API Gateway provides access to the protected resource. If the access token is expired, authorization server returns a specific error response. The client application can then use Refresh Token to request a new access token. The Authorization Server returns a new access token that can be used to access the protected resource.

    Note
    When a Policy violation event is logged in case of expired Oauth2 tokens, the application that is associated turn in to Unknown.
JWT Authentication Use Case and Workflow

JSON Web Token is a JSON-based open standard (RFC 7519) means of representing a set of information to be securely transmitted between two parties. A set of information is the set of claims (claim set) represented by the JWT. A claim set consists of zero or more claims represented by the name-value pairs, where the names are strings and the values are arbitrary JSON values. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure, enabling the claims to be digitally signed. JWTs can be signed using a shared secret (with HMAC algorithm), or a public or private key pair using RSA.

API Gateway can generate a JWT token itself or validate the JWT token generated by a trusted third-party server. API Gateway uses the RSA-based JWT to provide stronger integrity protection to JWTs when API Gateway is the issuer of the token. The JSON-based access tokens contain one or more claims. A claim is any piece of information that serves as an unique identifier, and that the token issuer who generated the token has verified. API Gateway extracts the claims from the JWT, identifies the application and then authorizes access to the protected resource.

Note
JWT authentication is supported for both REST and SOAP APIs.

Use case 1: JWT authentication with API Gateway as a JWT issuer

This describes the high level workflow for the scenario where API Gateway can generate the JSON Web Token itself.

  1. Configure API Gateway as an internal authorization server.
    For a complete procedure on configuring API Gateway as an internal authorization server, see Configuring the Internal Authorization Server.

  2. Enforce the Identify and authorize application policy on the API. Ensure to select JWT. For details of the Identify and authorize application policy see, Identify and Authorize Application.

  3. Associate an application with the API.
    You can create a new application or use an existing one. Ensure that you add the required claims while creating the application, which you would use to validate the access token. For a complete procedure on creating an application with a strategy, see Creating an Application. See Authorizations for applications created from Developer Portal for information on configuring authorization server for the applications created from Developer Portal.

  4. Activate the API.
    User on invoking the API uses the JWT identification method to access the protected resource.

  5. You get the JWT in one of the following ways (with or without claims), which you can pass as a bearer token to invoke the API.
    The following internal APIs are used for user and application authentication.

    getJsonWebtoken

    Used for user authentication without custom claims

    User authentication happens using the basic auth credentials of any valid IS user.

    • Method: GET

    • URL: http://hostname/rest/pub/apigateway/jwt/getJsonWebToken

    This endpoint can be used to create a JWT without custom claims.

    Used for application authentication with custom claims.

    If you want to add the custom claims in the JWT then you can use this URL with the payload specifying the custom claims.

    The application is authenticated using the application identifiers supplied in the request, such as, APIKey or Username or Host name, and then a token is generated with application id as a subject.

    • Method: POST

    • URL: http://hostname/gateway/security/getJsonWebToken

    This endpoint can be used to create a JWT with custom claims

    • Payload:

      	{
      	"claimsSet": {
      			"customclaim1": "name",
      			"customclaim2":"company name"
      				}
      	}
      

Use case 2: API Gateway with an external JWT issuer

This describes the high level workflow for the scenario where API Gateway accepts JSON Web Token generated by a trusted third-party server.

  1. Configure an external authorization server.
    For a complete procedure on configuring an external authorization server, see Adding an External Authorization Server.

  2. Enforce the Identify and authorize application policy on the API.
    Ensure to select JWT. For details of the Identify and authorize application policy see, Identify and Authorize Application.

  3. Associate an application with the API.
    You can create a new application or use an existing one. Ensure that you add the required claims while creating the application, which you would use to validate the access token and the external authorization server that would be the JWT issuer. For a complete procedure on creating an application with a strategy, see Creating an Application.

  4. Activate the API.
    User on invoking the API uses the JWT identification method to access the protected resource.

  5. Pass the JWT as a bearer token to invoke the API.

JWT Authorization Workflow

The flow of authorization requests and responses between the end user, client application, JWT issuer, and resource server is as depicted in the following figure:

icon

The JWT authorization workflow is as follows:

  1. The end user logs in, the client application sends an authentication request to API Gateway or to any third-party JWT issuer, to obtain a JWT token.

  2. If API Gateway is the JWT issuer, then it validates the user or the application. If the user or application credentials are valid, API Gateway generates the JSON token using a private key that was specified in the JWT configuration, and sends the generated token to the client.
    If the user credentials are invalid, API Gateway returns a specific error response.

  3. Client sends the generated JSON token in the HTTP Authorization request header as a Bearer token to access the protected API in API Gateway.

  4. API Gateway first identifies the application based on claims from the JWT, then validates the JWT using the public certificate of the issuer (the issuer can be API Gateway or a third-party issuer) and provides access to the protected resources.
    If the validation fails, API Gateway returns a specific error response.

    Note
    • If API Gateway has generated the JSON token, it validates the signature using a public certificate that was specified in the JWT configuration. Else, if the HTTP request is sent from a third-party JWT issuer, API Gateway validates the token using a public certificate or the JWKS URI of the issuer.
    • 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.

OpenID Authentication Use Case and Workflow

OpenID Connect is an open standard and decentralized authentication protocol that extends on the OAuth 2.0 authorization framework. It combines the capability of Open ID in verifying the client’s identity and OAuth’s capability of accessing the client’s resources.

In case of OpenID support in API Gateway, you can use the OpenID authentication protocol to identify and authorize a client application to access the protected resources in one of the following ways (these are explained in detail in the use cases.):

API Gateway does not act as a OpenID Connect server but can validate the tokens issued by other OpenID Connect servers.

The following internal API is used for getting an access token for an ID token.

exchangeIDToken

For details on scopes, see Mapping OAuth or OpenID Scopes.

Note
The getOpenIDtoken call is deprecated and is no more available from the API Gateway release 10.3 onwards.

Use case 1: OpenID authentication using OpenID Connect Provider

This describes the high level workflow for using the OpenID authentication protocol to identify and authorize a client application to access the protected resources.

  1. Configure a Provider if you are using the Dynamic client registration. Else you can proceed to step 2.
    For a complete procedure on configuring a provider, see Adding a Provider.

  2. Configure an external authorization server.
    Ensure you configure the external authorization server with the introspection URL and OAuth scopes. For a complete procedure on configuring an external authorization server, see Adding an External Authorization Server.

  3. Map the scopes.
    For a complete procedure on mapping scopes, see Mapping OAuth or OpenID Scopes.

  4. Enforce the Identify and authorize application policy on the API.
    Ensure to select OpenID Connect or JWT as options. For details of the Identify and authorize application policy see, Identify and Authorize Application.

  5. Associate an application with the API.
    You can create a new application or use an existing one. Ensure that the application associated contains the strategy for OpenID authentication. While creating a strategy you can associate it with the scopes that are available to be used while using dynamic client registration. For a complete procedure on creating an application with a strategy, see Creating an Application.

  6. Activate the API.
    User on invoking the API uses the access token or the ID token provided by the provider to access the protected resource.

  7. User can access the protected resources in one of the following ways:

    • The user presents the access token to API Gateway and on validation accesses the protected resource.

    • The user presents the ID token to API Gateway to exchange it for an access token (if the user has configured the OpenID Connect option in step 4). The client then presents the access token to API Gateway and on validation accesses the protected resource.

      The following internal API is used for getting an access token for an ID token.

      exchangeIDToken

      • Method: POST

      • URL: http://hostname/gateway/security/exchangeIDToken

      • Payload:

        {
        "gatewayScopes": ["OktaTenant1:inventory"],
        "idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjQwYzZiMDliNDQ5NjczNDUzYzNkYTY"
        "expiry": 3000
        }
        
    • The user presents the ID token as a JWT directly to API Gateway (if the user has configured the JWT option in step 4), and on validation accesses the protected resource.

OpenID Authorization Worklow

The OpenID Connect support in API Gateway provides two different ways for a client to access a protected resource depending on whether the provider has provided an access token or an ID token. The workflow diagram depicts both these cases. The first 2 steps are same in both the cases, the arrows in blue depict the flow where an access token is used to access the protected resource, and the arrows in orange depict the flow where an ID token is used to access the protected resource.

OpenID authorization workflow using the OpenID Connect Provider

The flow of authorization requests and responses between the end user, client application, OpenID Connect provider, and resource server is as depicted in the following figure. The client application makes an OpenID call to the OpenID Connect provider and receives an access token or an ID token in the response. It uses these tokens to access the protected resources.

icon

OpenID authorization workflow using the access token provided by the Open ID Connect Provider

  1. The client makes an OpenID call to the OpenID connect Provider.

  2. The OpenID Connect Provider provides an access token to the client.

  3. The client application presents the access token received from the OpenID Connect Provider to send HTTP requests to API Gateway.

  4. API Gateway then performs the following:

    a. Identifies the application using the client ID.

    b. Validates the token locally or remotely if it is not possible locally.

    c. Checks if the requested resource is part of the scopes in the token.

    d. Checks the audience.

    API Gateway provides access to the protected resource if all the validations are done. If the access token is valid, API Gateway provides access to the protected resource. If the access token is expired, authorization server returns a specific error response. The client application can then use Refresh Token to request a new access token. The Authorization Server returns a new access token that can be used to access the protected resource.

OpenID authorization workflow using the ID token provided by the Open ID Connect Provider

  1. The client makes an OpenID call to the OpenID Connect Provider.

  2. The OpenID Connect Provider provides an ID token to the client.

  3. The client application presents the ID token received from the OpenID Connect Provider to API Gateway.

  4. API Gateway validates the ID token and returns an access token to the client application.

    The following internal API is used for getting an access token for an ID token.

    exchangeIDToken

    • Method: POST

    • URL: http://hostname/gateway/security/exchangeIDToken

    • Payload:

      {
      "gatewayScopes": ["OktaTenant1:inventory"],
      "idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjQwYzZiMDliNDQ5NjczNDUzYzNkYTY"
      "expiry": 3000
      }
      

    For details on mapping scopes, see Mapping OAuth or OpenID Scopes.

  5. The client then uses this access token to send HTTP requests to API Gateway.

  6. API Gateway then performs the following:

    a. Identifies the application using the client ID.

    b. Validates the token locally or remotely if it is not possible locally.

    c. Checks if the requested resource is part of the scopes in the token.

    d. Checks the audience.

    API Gateway provides access to the protected resource if all the validations are done. If the access token is valid, API Gateway provides access to the protected resource. If the access token is expired, authorization server returns a specific error response. The client application can then use Refresh Token to request a new access token. The Authorization Server returns a new access token that can be used to access the protected resource.

Note
The user can present the ID token directly as a JWT to access the protected resources in case the ID token is provided on configuring the JWT property in the Identify and authorize application policy enforced on the API.

Secure API using OAuth2 with refresh token workflow

When using the authorization code grant type to get the access token, you need to get the permission from the resource owners at least for the first time. In the subsequent attempts to get the access token, if you do not want to get the permission from the resource owners, then you can use the refresh token.

This use case explains how to secure the API using OAuth2 authentication strategy. It also explains the refresh token workflow in detail.

Configuring OAuth2 Authentication with Refresh Token

This use case explains how to secure the API using OAuth2 authentication strategy with authorization_code and refresh_token grant types.

The use case starts when you create an API and ends when you create an application strategy with OAuth2 authentication scheme.

To configure OAuth2 Authentication with Refresh Token

  1. Create an API. For details about creating an API, see Creating an Rest API.

  2. Enable the OAuth2 token identification type in the Identify & Authorize policy. For details about Identify & Authorize policy, see Identify & Authorize.

  3. Create OAuth scope in the local authorization server.

  4. Map the OAuth scope to the API scope. For details about mapping OAuth scope, see Mapping OAuth or OpenID Scopes.

  5. Create an application with OAuth2 authentication strategy.

    a. Create a new application.

    For details about creating an application, see Creating an Application.

    b. Associate the application with the API that you have created.

    c. Click the Authentication tab to create strategy with OAuth2 authentication.

    d. Select the Authentication schemes as OAUTH2.

    e. Specify the Authentication server as local.

    f. Enable the Generate credentials toggle button to generate the client dynamically in the authorization server and provide the following information:

    i. Select the Application Type as Confidential. A confidential client is an application that can keep a client password confidential to the world. This client password is assigned to the client app by the authorization server. This password is used to identify the client to the authorization server, to avoid fraud. An example of a confidential client could be a web app, where no one but the administrator can get access to the server, and see the client password.

    ii. Select the application profile from the Application profile drop-down menu. For example, web.

    iii. Specify the duration in seconds for which the access token is active in the Token lifetime (seconds).

    iv. Specify the number of times you can use the refresh token in the Token refresh limit to get a new access token.

    Note
    To use refresh token unlimitedly, specify the limit as -1.

    v. Specify the URIs that the authorization server can use to redirect the resource owner’s browser during the grant process. You can add multiple URIs by clicking +Add.

    vi. Specify the grant type to be used to generate the credentials. For this specific use case, we have selected authorization code, client_credentials, and refresh_token, which are dynamically populated from the authorization server.

    Note
    Make sure you have selected refresh_token grant_type, if you want to get the refresh tokens.

    vii. Select the scopes that are to be mapped for the authentication strategy.

    viii. Click Add to save the strategy.

    ix. Click Save to save the application.

Refresh Token Process Flow

This use case explains the following workflow:

How to get the access token with resource owner permission?

This use case starts when you get the authorization code and ends when you access then API.

To get access token using authorization code grant type (With resource owner permission)

  1. Get authorization code.

    a. Click the http(s)://hostname/invoke/pub.apigateway.oauth2/authorize?response_type=code&redirect_uri=<redirectURI>&client_id=<Client ID>.

    Note
    Make sure you have replaced the <redirectURI > and <ClientID > in the above mentioned URL. You can get the redirect URI and client ID from the Authentication tab of the Application screen.

    b. Click the Approve button.

    c. Enter the credentials of your API Gateway instance.

    You will be re-directed to the redirect URI as per to the configuration. The below screenshot is just a sample, you will be redirected to a different URL based on your configuration and so the screenshot varies accordingly . If the given redirect URI is not a valid web page, you may get a Page not found error, which is fine, because we get the authorization code value from the browser URL.

    d. Make a note of the authorization code that is displayed in the address bar of the browser. As highlighted in the above image’s URL, you can see the authorization code in the code= field of the URL.

  2. Get Access Token.

    a. Invoke the access token endpoint.

    Request: POST http(s):// hostname/invoke/pub.apigateway.oauth2/getAccessToken

    In the Authorization tab, select the authorization type as Basic Auth. Provide the client ID as username and client secret as password. You can get the client ID and client secret in the Authentication tab of the Application screen.

    Sample request body

    {
               "redirect_uri":"http://test.com",
               "scope":"email",
               "grant_type":"authorization_code", 
               "code":"4b4b16c68f1c4b6fa7f26e0cb00b5daa"
    }
    
    Note
    You must replace the redirect_URI, scope, and code with appropriate values. For the code field value, make sure you use the authorization code that you have noted down in the previous step.

    Sample response body

    {
            "scope": "TestRefreshtoken",
            "access_token": "c92b6227a19c46f1a6545bf370bb6ee6e30ff87957ef4b1aaa9577f7e86e4bd7",
            "refresh_token": "f78dd4fc5b8d4d799cf066427e828e26ce7e3723e4334416a7b9cd8a274e6947",
            "token_type": "Bearer",
            "expires_in": 3600
    }
    
  3. Access API using the REST API client.
    In the Authorization tab, select the authorization type as Bearer Token and provide the access token that you get from the response payload of the previous step.

How to get the access token without resource owner permission using refresh token in the subsequent attempts?

This use case starts when you get the authorization code and ends when you access then API.

To get access token using refresh token (Without resource owner permission)

When the access token expires and if you need to access the same API, you need to get another access token. If you have refresh token, you can get a new access token without getting the permission from the resource owner.

  1. Invoke the access token endpoint.

    Request: POST http(s)://hostname/invoke/pub.oauth/refreshAccessToken

    In the Authorization tab, select the authorization type as Basic Auth. Provide the client ID as username and client secret as password. You can get the client ID and client secret in the Authentication tab of the Application screen.

    Sample request body

    {
    "grant_type":"refresh_token", 
    "refresh_token":"f78dd4fc5b8d4d799cf066427e828e26ce7e3723e4334416a7b9cd8a274e6947"
    }
    
    Note
    Make sure you have replaced the refresh token that you got from the Step 2 using How to get the access token with resource owner permission? use case.

    Sample response body

    {
    "grant_type": "refresh_token",
    "refresh_token": "f78dd4fc5b8d4d799cf066427e828e26ce7e3723e4334416a7b9cd8a274e6947",
    "scope": "TestRefreshtoken ",
    "access_token": "c102bcaebecf451ca705bf54d26fae732ea9790a0ff64a87a010b3875b4b8da2",
    "token_type": "Bearer",
    "expires_in": 3600
    }
    
  2. Access API using the REST API client.
    In the Authorization tab, select the authorization type as Bearer Token and provide the access token that you get from the response payload of the previous step. .

Securing Access Token Calls with PKCE

PKCE (Proof Key for Code Exchange - RFC 7636) is supported to enhance the security of the OAuth 2.0 authorization code grant. PKCE is applicable only for public OAuth clients that use the authorization code grant, which are vulnerable to the Man In The Middle (MITM) attack. In such cases, the client application should enforce PKCE by giving proof to the authorization server that the authorization code belongs to the client application. Only then the authorization server issues an access token for the client application. For more information about PKCE specification, see https://datatracker.ietf.org/doc/html/rfc7636.

Note
  • Use of PKCE is optional.
  • By default, API Gateway does not enforce PKCE. API Gateway provides backward compatibility support for APIs migrated from the 10.1 version or higher.
  • When you import an application from older version of API Gateway, by default, API Gateway uses the global PKCE setting.
  • API Gateway supports securing the get access token calls with PKCE, when API Gateway acts as a local authorization server.
  • When an external authorization server is used, API Gateway is not involved or remains out of scope with regards to how the consumer application retrieves a token from the external authorization server or its security arrangements. In such scenarios, API Gateway is involved only when validating the token before giving an application access to the API(s).

The PKCE flow works with these parameters:

When you enforce PKCE, the public OAuth client creates a secret called the code verifier. The client also generates the code challenge for the corresponding code verifier. The PKCE flow is explained as follows:

  1. When the client invokes the authorization endpoint (http(s)://hostname/invoke/pub.apigateway.oauth2/authorize) on the authorization server, the client sends the code challenge and code challenge method to the authorization server.

  2. The authorization server validates the request. If the request is valid, the authorization server generates the authorization code and saves the supplied code challenge and code challenge method in the OAuthPKCE cache.

  3. The client invokes the token endpoint (http(s)://hostname/invoke/pub.apigateway.oauth2/getAcessToken) on authorization server to exchange the authorization code for an access token. The client also supplies the additional input parameter code verifier.

  4. Authorization server applies the code challenge method to the supplied code verifier and generates the code challenge. If the generated code challenge value matches with the code challenge value supplied to the authorization endpoint service (in step 1), then the token endpoint service issues the access token to the client.

The following diagram summarizes the PKCE flow:

In API Gateway, you can enforce PKCE at the following levels:

  • Global level. Using a platform-level global setting, you can enforce PKCE for all the applications. For more information about how to enforce PKCE at global level, see How do I enforce PKCE globally?
  • Application level. On a need to have basis, you can also enforce PKCE for a specific application. For more information about how to enforce PKCE at application level, see How do I enforce PKCE at application level?
  • The flow chart explains when the API Gateway enforce and does not enforce the PKCE.

    How do I enforce PKCE globally?

    This section explains how to enforce PKCE globally in the local authorization server. When you enforce PKCE at global level, then it is applied for all the public OAuth2.0 clients of local authorization server.

    To enforce the PKCE at global level

    1. Expand the menu icon, in the title bar, and select Administration.

    2. Select Security > JWT/OAuth/OpenID.
      The Authorization servers section displays a list of available internal and external authorization servers.

    3. In the Internal authorization servers section, click local .

    4. Expand the OAuth configurationsection, select the Enforce PKCE checkbox.

    5. Click the Update button.
      Once you enforce PKCE, you get access token only on successful validation of code verifier.

    How do I enforce PKCE at application level?

    This section explains how to enforce PKCE at an application level in the local authorization server. When you enforce PKCE at an application level, it is enforced only for that application.

    To enforce PKCE at an application level

    1. Create OAuth scope in the local authorization server.

    2. Create a new application or update an existing application with OAuth2 authentication strategy.

      For details about creating an application, see Creating an Application.

    3. Open the application and click the Authentication to create a strategy with OAuth2 authentication.

      Make sure you have selected the following mandatory fields for this use case:

      • Select the Authentication schemes as OAUTH2.
      • Specify the Authentication server as local.
      • Select the Application Type as Public.
      • Specify the grant type to be used to generate the credentials. For this specific use case, you must select authorization_code, which is dynamically populated from the authorization server.
      • In the Enforce PKCE section, select one of the following:
      • PKCE Settings Description
        Enforced

        If you select this option, the local authorization server enforces PKCE even if the PKCE is not enforced at the global level.

        Not Enforced

        If you select this option, the local authorization server does not enforce PKCE even if the PKCE is enforced at the global level.

        Use Global Setting (Enforced) If you select this option, the local authorization server enforces PKCE based on the PKCE setting at the global level.
        Note: The value inside the parenthesis depicts whether you have enforced the PKCE at the global level or not.
        For details about how to enforce PKCE at global level, see How do I enforce PKCE globally?

        Note
        The application level PKCE enforcement takes precedence over the global level PKCE enforcement.

      • Specify the postman https://oauth.pstmn.io/v1/callback URL as redirect URI.
      • Specify the OAuth scope that you have created for the local authorization server in Step 1.

    4. Click Add to save the strategy.

    5. Click Save to update and save the application.
      Once you enforce PKCE, you get access token only on successful validation of code verifier.

    How do I secure the access token with Authorization Code (With PKCE) grant type using postman?

    This section explains how to secure the get access token calls using postman.

    To test the access token

    1. In the Postman, under the Authorization tab, select the authorization type as OAuth2.0 from the TYPE drop-down menu.

      a. In the Configure New Token section, select the grant type as Authorization Code (With PKCE).

      b. Type the redirect URL as https://oauth.pstmn.io/v1/callback in theCallback URLtext box.

      c. Select the Authorize using browser check box.

      d. Type the authorization URL as http(s)://hostname/invoke/pub.apigateway.oauth2/authorize in the Auth URL text box.

      e. Type the http()://hostname/invoke/pub.apigateway.oauth2/getAccessToken in the Access Token URL text box.

      f. Type the client ID and client secret in the Client ID and Client Secret text boxes respectively.

      Note
      You can get the client ID and client secret from the Authentication tab of the Application screen.

      g. Select the hashing method used to generate the code challenge from the Code Challenge Method drop down menu.

      h. Specify the OAuth scope that you have created for the local authorization server in Step 1 in the Scope text box.

      i. Select the client authentication as Send client credentials in body.

      j. Click the Get New Access Token button.

      k. Click the Approve button.
      TheMANAGE ACCESS TOKENS pop-up window displays the access token.

    How do I secure the access token by directly calling API Gateway’s REST APIs?

    This section explains how to secure the get access token calls when you enforce the PKCE using REST APIs.

    Before you begin

    Ensure that you have:

    To secure the access token

    1. Get authorization code.

      a. Call the authorize endpoint using a REST client.
      http(s)://hostname/invoke/pub.apigateway.oauth2/authorize? response_type=code&redirect_uri=&client_id=&code_challenge=&code_challenge_method=S256

      Note
      Make sure you have replaced the redirectURI , ClientID, and Code_Challenge in the above mentioned URL. You can get the redirect URI and client ID from the Authentication tab of the Application screen.

      b. Click the Approve button

      c. Provide the credentials of API Gateway user to approve the request.

      You are re-directed to the redirect URI as per the configuration in the application strategy. The screenshot below is just a sample, you are redirected to a different URL based on your configuration, so the screenshot varies accordingly. If the given redirect URI is not a valid web page, you might get a Page not found error, which is fine, because we get the authorization code value from the browser URL.

      d. Make a note of the authorization code.

      Note
      If the redirect URL screen is not able to display the authorization code, then you can take it from the address bar of the browser. As highlighted in the above image’s URL, you can see the authorization code in the code=field of the URL.

      e. Click Save to save the application.

    2. Get access token.

      a. Invoke the access token endpoint using a REST client.
      Request: POST http(s)://hostname/invoke/pub.apigateway.oauth2/getAccessToken.

      You need to pass authorization header using basic authentication with the client ID as username and client secret as the password. You can get the client ID and client secret in the Authentication tab of the Application screen in the API Gateway UI.

      Sample request body

      {
      "redirect_uri":"http://test.com",
      "scope":"email",
      "grant_type":"authorization_code",
      "code":"0025abe9f96d4901b61340344c29a576",
      "code_verifier":"a4793f15479a4c5697f93b44d055ab6cbd16be50400a4591892f914b1a256da8",
      "client_id":"374b1fae-4405-411b-85a0-6e1ab90923ba"
      }
      
      Note
      You must replace the redirect_URI, scope, code, and code_verifier with appropriate values. For the code field, make sure you use the authorization code you noted down in the step 1.d.

      Sample response body

      {
      "access_token": "b5b33bc9c57945f388010f8caf5fe9b6b14abef468d346e68e0cd374c0df60d7",
      "token_type": "Bearer",
      "expires_in": 3600
      }
      
    How do I enforce PKCE selectively for each access token call?

    You can enforce PKCE specific to each GET access token call. To perform this use case, you must clear the Enforce PKCE check box in the Administration > Security > JWT/OAuth/OpenID screen. When you disable the PKCE global option, by default PKCE is not verified. But if you send the authorize request with the code challenge and code challenge method parameters, you get an access token with PKCE verification.

    How do I generate code verifier and code challenge?

    To generate code verifier and code challenge

    1. You can generate code verifier and code challenge using the Postman tool. You can select the code challenge method and postman automatically generates the code verifier for you. For more details, see How do I secure the access token with Authorization Code(With PKCE) grant type using postman?

    2. Additionally, If you want to create a code verifier and code challenge on your own, please follow the instructions available in the PKCE RFC document RFC 7636, particularly sections 4.1 and 4.2

    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.

    Authorize User

    This policy authorizes incoming requests against a list of users, a list of groups, or users who belong to LDAP groups registered in API Gateway.

    Note
    LDAP groups cannot be authorized using the List of Groups configuration option. To authorize a user who belongs to an LDAP group, you must first create a team containing one or more LDAP groups and then authorize the user using List of Teams configuration option in this policy.

    Use this policy in conjunction with an authentication policy (for example, Require HTTP Basic Authentication, Require WSS Username Token).

    The table lists the parameters of this policy and how they are applied to authorize the incoming requests.

    Parameter Description
    List of Users Authorizes applications against a list of users registered in API Gateway.
    Type a search string, select a user, and click icon to add. You can add more users.
    Click icon to delete the user added.
    List of Groups Authorizes applications against a list of groups registered in API Gateway.
    Type a search string, select a group, and click icon to add. You can add more groups.
    Click icon to delete the group added.
    List of Teams Authorizes applications against a list of teams registered in API Gateway.
    Type a search string, select a team, and click icon to add. You can add one or more teams.
    Click icon to delete a team.

    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:

    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:
    This is not applicable to a GraphQL API.
    • 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.

    Schema validation for GraphQL API:
    The incoming query or mutation payloads are validated against the GraphQL schema type system.
    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 This is not applicable to a GraphQL API. 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 This is not applicable to a GraphQL API. 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

    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>
        
    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.xpathForexample:{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.

    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.

    Note
    Data masking can not be performed for:
    • Payloads that are sent as streams.
    • Incoming headers from the client.

    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.

    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:{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.

    For a REST API, the ${sys:resource-path} alias in the Endpoint URI is replaced by the resources and query parameters of the native service.

    For a GraphQL API, the ${sys:query_string} alias in the Endpoint URI is replaced by the query string of the native service.

    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 aliassyntaxinthepolicybeforecreatingthealiasasendpointalias,APIGatewayconsiders{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).

    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:{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 aliassyntaxinthepolicybeforecreatingthealiasasendpointalias,APIGatewayconsiders{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:{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 aliassyntaxinthepolicybeforecreatingthealiasasendpointalias,APIGatewayconsiders{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.11.

    10.5 Conditional Variable 10.5 Condition Operator 10.11 Transformation Variable 10.11 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:{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 aliassyntaxinthepolicybeforecreatingthealiasasendpointalias,APIGatewayconsiders{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:{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 aliassyntaxinthepolicybeforecreatingthealiasasendpointalias,APIGatewayconsiders{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:dynEndpointwillbereplacedwith{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:{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 aliassyntaxinthepolicybeforecreatingthealiasasendpointalias,APIGatewayconsiders{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:{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 aliassyntaxinthepolicybeforecreatingthealiasasendpointalias,APIGatewayconsiders{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:{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 aliassyntaxinthepolicybeforecreatingthealiasasendpointalias,APIGatewayconsiders{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.

    Failover behavior during load balancing

    When an endpoint that is configured in Load balancer routing returns any of these exceptions - ConnectException, MalformedURLException, NoRouteToHostException, ProtocolException, SocketTimeoutException, UnknownHostException, UnknownServiceException - then API Gateway treats the endpoint to be inactive and routes to the next endpoint as per the round-robin strategy. In this case, the endpoint is suspended for the duration mentioned in the suspendDuration parameter (default is 30s), which indicates the duration to suspend the endpoint without repeatedly trying to reach it.
    In this way API Gateway tries to invoke all the endpoints configured in the load balance routing. If all endpoints return downtime error, API Gateway returns a Service is down error.
    If an endpoint returns an exception other than the Downtime exception then that exception is sent to the client and the remaining endpoints are not invoked.
    You can control the behavior of considering Downtime exceptions only for load balancing through the extended property pg.lb.failoverOnDowntimeErrorOnly, which you can set through Administration > General > Extended settings page. The default value of this property is true. If you set the value to false all failures from the endpoint are treated as downtime and load balancing takes place.

    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.
    • If the WSDL used to create the SOAP API includes ws:Policy elements, the system considers those entries for outbound authentication. Otherwise, the specified parameters within the Outbound Auth - Message policy will take effect.
    • If the WSDL used to create the SOAP API contains ws:Policy elements and the Outbound Auth - Message policy is not specified, then the ws:Policy elements have no effect. The ws:Policy elements are not exposed when the WSDL is retrieved from API Gateway.

    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.
    Stage Specify a stage, if you want the configuration to be applicable to a specific stage.

    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
    • Developer 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.Forexample,iftestistheemailalias,thentype{emailaliasname}. For example, if test is the email alias, then type {test}.

    Traffic Optimization

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

    The Traffic optimization policy generates two types of events when the specified limit is breached:

    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 appears as the rule name and you cannot modify this.
    Operator Specifies the operator that connects the rule to the value specified.

    Select one of the operators: Greater Than, Less Than, Equals To. By default, the Greater Than operator is selected. It indicates that the throttling rule is applied when the Total Request Count for an API is greater than (exceeds the limit specified for) the value specified in the Value field.

    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
    • Developer 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.Forexample,iftestistheemailalias,thentype{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-specific throttling Specifies whether the configured invocation limit has to apply to all consumer applications together or to each application individually.
    Note: This field is applicable only when you select the required applications from the Consumer Applications field.
    Possible values:
    • If this option is selected, each application specified in the Consumer Applications field is allowed to invoke the API the specified number of times within the given time limit. For example, consider the following:

      You have specified consumer applications Consumer1 and Consumer2 and you allow 100 invocations per minute.

      Then, Consumer1 can perform up to 100 invocations per minute and Consumer2 as well can perform the same without policy violation.

    • If this option is not selected, the specified invocation limit is applied to all consumer applications together. For example, consider the following:

      You have specified consumer applications Consumer1 and Consumer2 and you allow 100 invocations per minute.

      Then, both consumer applications together can invoke the API for 100 times per minute without policy violation.

    Consumer Applications Specifies the consumer applications for which the policy is applied. Do one of the following:
    • Select the required consumer applications. Type a keyword to find the required application and click + to add it.
    • Select an option to apply the configured invocation limit:
      • All consumers. To apply the invocation limit to all consumers. All consumer applications - including the registered, global applications, and default applications - to invoke the API the specified number of times within the given time limit. That is, the specified invocation limit is shared by all consumer applications.

        For example, if you specify 1000 invocations per minute for an API, then the total number of invocations performed by all consumer applications in a minute cannot exceed 1000.

      • All registered consumers. To apply the invocation limit to all registered consumers. Allows all registered consumer applications to invoke the API the specified number of times within the given time limit. That is, the specified invocation limit is shared by all registered consumer applications. The registered consumer applications are the applications that are registered with API to which the policy is applied.

        For example. if you specify 1000 invocations per minute for an API, then the total number of invocations performed by all registered consumer applications in a minute cannot exceed 1000.

      • All non-registered consumers. To apply the invocation limit to all non-registered consumers. Allows all non-registered consumer applications to invoke the API for the specified number of times within the given time limit. That is, the specified invocation limit is shared by all non-registered application. The non-registered applications are the applications that are not registered with the API to which the policy is applied.

        For example, if you specify 1000 invocations per minute for an API, then the total number of invocations performed by all non-registered consumer applications in a minute cannot exceed 1000.

        Note: You can invoke an API using a non-registered consumer application only if the Global applications or Global applications and DefaultApplication option is selected from the Application Lookup Control field of the corresponding Identify & Authorize policy.

      • Each consumer. To apply the invocation limit to each consumer. Allows each consumer application to invoke the API the specified number of times within the given time limit. That is, the specified invocation limit is applicable individually for each consumer application.

        For example, if you specify 1000 invocations per minute for an API, then each consumer application can perform 1000 invocations in a minute

      • Each registered consumer. To apply the invocation limit to each registered consumer. Allows each registered consumer application to invoke the API the specified number of times within the given time limit. That is, the specified invocation limit is applicable individually for each registered consumer application.

        For example, if you specify 1000 invocations per minute, then each registered consumer application can perform 1000 invocations in a minute.

      • Each non-registered consumer. To apply the invocation limit to each non-registered consumer. Allows each non-registered consumer application to invoke the API the specified number of times within the given time limit. That is, the specified invocation limit is applicable individually for each non-registered consumer application.

        For example, if you specify 1000 invocations per minute, then each non-registered consumer application can perform 1000 invocations in a minute.

      The invocation limit applied to newly added applications depends on the application type. The time limit starts when the associated API is activated or the application is associated to the policy. For example, consider the following:

      API-level Traffic Optimization policy configured with invocation limit as 500 for 5 minutes, for All registered consumers. The available registered consumers are Consumer1 and Consumer2.

      When you activate the policy, the two consumers together perform 200 invocations in 2 minutes. Register a new consumer application, Consumer3 to the list after 2 minutes from the start time. Then, all three consumers perform the remaining 300 invocations during the last 3 minutes without violating the policy.

      Let us see one more example.

      Global Traffic Optimization policy configured with invocation limit as 100 for 15 minutes, for Each consumer. The available consumers are Consumer1 and Consumer2.

      When you activate the policy, the each consumer performs 100 invocations in 10 minutes. Add a new consumer application, Consumer3 to the list after 2 minutes from the start time. Then, the new consumer can also perform 100 invocations during the last 5 minutes without violating the policy.

    Note: If you select All consumers or Each consumer from this field and specify Registered applications from the Application Lookup Control field of the corresponding Identify & Authorize policy, then only the registered applications are allowed to invoke the API. In such scenarios, only the registered consumer applications can utilize the specified invocation limit.

    You can invoke APIs using non-registered consumer applications only if the Global applications or Global applications and DefaultApplication option is selected from the Application Lookup Control field of the corresponding Identify & Authorize policy.

    Traffic Optimization Policy Enforcement Scenarios

    You can enforce more than one Traffic Optimization policy for an API based on your requirement. This section lists a sample requirement scenario and the possible solution:

    How do I?

    Possible solution:

    Create two Traffic Optimization policies with the following specifications

    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 stores in the cache using an allowlist. 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:

    Monitor Performance

    This policy is similar to the Monitor Service Level Agreement 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 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 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 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
    • Developer 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.Forexample,iftestistheemailalias,thentype{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 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 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 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
    • Developer 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.Forexample,iftestistheemailalias,thentype{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.

    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:

    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

    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>
        
    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.xpathForexample:{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.

    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.

    Note
    Data masking can not be performed for:
    • Payloads that are sent as streams.
    • Native API’s response headers.

    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.

    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:

    Property Description
    Allowed Origins Specifies the origin from which the responses originating are allowed.

    syntax for the origin: scheme://host:port

    You can add multiple origins by clicking .

    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 .

    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 .

    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.

    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.
    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.
    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.xpathForexample:{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.

    Note
    API Gateway does not mask the payload, if the payload is sent as a stream.

    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.

    Policy Validation and Dependencies

    The following table shows:

    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 GraphQL None. None. No. API Gateway includes only one policy in the effective policy.
    Identify and Authorize Application REST SOAP GraphQL 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 GraphQL 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 Service Level Agreement 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 GraphQL 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 GraphQL None. None. No. API Gateway includes only one policy in the effective policy.

    Variable Framework

    This figure depicts how the variable framework is used to access the variables in various policies across stages.

    Note
    Any variables that access the request or response payloads cannot be used in the variable framework, if the payload is sent as a stream.

    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:

    Note
    While xpath and jsonPath are applicable only to payload, regEx can be used with both payload and 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.
    ${request.payload.native.xpath [EXPR]} In SOAP to REST context, this variable returns the SOAP request to be sent to the native API.

    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.
    ${response.payload.native.xpath [EXPR]} In SOAP to REST context, this variable returns the native SOAP response, returned by the native SOAP API.

    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 and port 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.
    ${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.
    Note
    ${gatewayHostname} is removed as it is not supported in API Gateway Cloud.

    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.11 the existing variable framework is enhanced to support the following use cases:

    Custom Policy Extension

    API Gateway provides a range of out-of-the-box policies to address common API management requirements like security, transformation, validation, error processing, and so on. In addition, API Gateway provides an option to add custom extensions or custom variables.

    Custom Extensions

    You can add these custom extensions into API Gateway policy stages to handle a requirement that might not be handled by any of the existing policies. You can use custom extensions in conjunction with the existing policies across stages. For example, if you want to invoke a third-party API or call an external endpoint during any stage of API processing, you can add custom logic in the corresponding policy stage and use it as required.

    API Gateway supports the following custom extension types:

    Custom extensions are applicable to the REST, SOAP and OData API types. Custom extensions are supported at all levels such as, API, Scope, Global and can be added in any or all policy enforcement stages except the transport policy and the traffic monitoring policy stages.

    The figure depicts a sample workflow for custom extension support in the request and response processing stages in API Gateway:

    Custom Variables

    You can configure custom variables under custom extension policy. You can assign a value or a variable expression to a custom variable which can be used in other policy parameters. Custom variable also provides option to set custom field to the transactional events. To set the custom fields, you have to define customTransactionFields.FIELD_NAME custom variable. It also provides an option to configure namespaces for Xpath expressions. To configure the namespaces you have to define XpathNamespaces custom variable.

    How Do I Invoke a Service through HTTP/HTTPS using Custom Extension?

    This use case explains how to invoke a service through HTTP/HTTPS using custom extension. The custom extension configured can be enforced in any of the policy stages and used during API processing.

    The use case starts when you have an API that has to be enforced with a custom extension and ends when you successfully invoke the API with the custom extension enforced.

    To invoke a service through HTTP/HTTPS using custom extension

    1. Ensure you have the external endpoint URL to be invoked during API processing using a custom extension.

    2. Click APIs on the title navigation bar.

    3. Click the required API.
      The API details page appears.

    4. Click Edit.

    5. Select Policies.

    6. Click Required Policy stage > Custom Extension.
      This adds the custom extension policy where you can configure the required properties.

    7. Click to open the policy properties section in a full page.

    8. Provide the following information in the Conditions section, as required:

      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 executes this policy when all the configured conditions comply in the respective policy stage.
      • OR. This is selected by default. API Gateway executes this policy when any one of the configured conditions complies.
      • 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
        • 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 Variables Available in API Gateway.

    9. Click Custom Action.

    10. Select External endpoint in the custom extension Type field.

    11. Provide the following information in the External Endpoint section, as required:

      Property Description
      Endpoint URI Provide the external endpoint URI that you want to invoke.
      Method Specify the method exposed by the API. Available values are: PUT, POST, GET, DELETE, HEAD, CUSTOM.

      Note: If you select CUSTOM, the HTTP method in the incoming request is sent to the native API.
      SSL Configuration Specifies the required SSL configuration details of the external endpoint. Provide the following information:

      • Keystore Alias. Specifies the keystore alias. For details on Keystore configuration, see Keystore and Truststore.

      • 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. For details on Truststore configuration, see Keystore and Truststore.

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

      • Read Timeout (seconds). Specifies the time interval (in seconds) after which a socket read attempt times out.
      Path Parameters Specifies the path parameter you want to configure to your custom extension. Provide the following information:

      • Path Parameter Name. Species the name of the path parameter you want to configure in your custom extension. This path parameter name should be present in the endpoint URL enclosed with {} to be replaced at runtime. For example, define external URL as http://host/authors/{id}/books and provide id as path parameter name with the value you need to populate at runtime.

      • Path Parameter Value. Specifies the value for the path parameter specified.
    12. Configure the custom properties of the custom extension as required.
      For details about the custom extension properties and their descriptions, see Custom Extension Properties.

    13. Click Save.
      The API is saved with the added custom extension.

    14. Invoke the API.
      The applied custom extension invokes the mentioned HTTP/HTTPS endpoint and processes as configured.

    How Do I Invoke an AWS Lambda Function using Custom Extension?

    This use case explains how to invoke an AWS Lambda function using custom extension. The custom extension configured can be enforced in any of the policy stages and used during API processing.

    The use case starts when you have an API that has to be enforced with a custom extension and ends when you successfully invoke the API with the custom extension enforced.

    To invoke an AWS Lambda function using custom extension

    1. Create a Lambda function and ensure it is active.
      For details on how to create an AWS Lambda function, see https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html.

    2. Configure AWS alias.
      For details on how to configure an AWS alias, see Configuring an AWS Alias.

    3. Click APIs on the title navigation bar.

    4. Click the required API.
      The API details page appears.

    5. Click Edit.

    6. Select Policies.

    7. Click Required Policy stage > Custom Extension.
      This adds the custom extension policy where you can configure the required properties.

    8. Click to open the policy properties section in a full page.

    9. Provide the following information in the Conditions section, as required:

      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 executes this policy when all the configured conditions comply in the respective policy stage.
      • OR. This is selected by default. API Gateway executes this policy when any one of the configured conditions complies.
      • 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
        • 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 Variables Available in API Gateway.

    10. Click Custom Action.

    11. Select AWS Lambda in the custom extension Type field.

    12. Provide the following information in the AWS Lambda section, as required:

      Property Description
      Function Name Provide the AWS Lambda function name you want to invoke. As this property supports variable framework, you can use the available Function Name variables. For details about the variables available in API Gateway, see Variables Available in API Gateway.
      Invocation Type Specify the AWS invocation type, asynchronous or synchronous. Available options are:

      • RequestResponse (synchronous type)

      • Event (asynchronous type)
      AWS Alias Provide the AWS alias configured for the AWS account.
      Client Configuration Provide the following client configuration details and click .

      • Name. Start typing the client property name and select the required property from the type-ahead search results displayed.

        API Gateway supports the following properties that you can configure: Socket timeout(ms), Connection timeout(ms), Request timeout(ms), Connection expiration timeout(ms), Maximum Coneection idle time(ms), Client execution timeout(ms), Server error retry count, Enable throttle retries, Maximum client retry count, TCP send buffer size hints, TCP receive buffer size hints, Enable gzip requests, Enable Expect-Continue, Enable host prefix injection, Enable Keep-alive, Enable, Response metadata caching, Response metadata cache size, and Signature Algorithm.

      • Value. Provide a value for the client property specified. You can configure multiple properties.

        For details about the supported client properties, see the following AWS documents:

    13. Configure the custom properties of the custom extension as required.
      For details about the custom extension properties and their descriptions, see Custom Extension Properties.

    14. Click Save.
      The API is saved with the added custom extension.

    15. Invoke the API.
      The applied custom extension invokes the AWS lambda function and processes as configured.

    How Do I Define a Custom Variable?

    This use case explains how to define custom variable using custom extension. The defined custom variable can be used in any of the subsequent policy stages during API processing.

    The use case starts when you have to define a custom variable, which is not available in API Gateway and ends when you successfully defined and accessed the variable in the subsequent policy stages.

    To define a custom variable using custom extension

    1. Click APIs on the title navigation bar.

    2. Click the required API.
      The API details page appears.

    3. Click Edit.

    4. Select Policies.

    5. Click Required Policy stage > Custom Extension.
      This adds the custom extension policy where you can configure the required properties.

    6. Click to open the policy properties section in a full page.

    7. Provide the following information in the Conditions section, as required:

      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 executes this policy when all the configured conditions comply in the respective policy stage.
      • OR. This is selected by default. API Gateway executes this policy when any one of the configured conditions complies.
      • 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
        • 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 Variables Available in API Gateway.

    8. Click Custom Variable.

    9. Provide the following information in the Define Custom Variable section, as required:

      Property Description
      Custom Variable Specify the custom variable with a syntax to be accessed across subsequent stages and click Add.
      • Variable. Specifies the custom variable with a syntax.
      • Value. Specifies a plain value or value with a syntax.
      For example, if you want to use the client’s request related information like content-type header at response stage, you can define the clientContentTypecustomvariabletostorethe{clientContentType} custom variable to store the {request.headers.Content-Type} variable. The ${clientContetType} custom variable can be accessed in any other policy across subsequent stages such as response or error processing stage. For details about the variables available in API Gateway, see Variables Available in API Gateway.
    10. Provide the following information in the Custom Extension Metadata section, as required. This is applicable only for XML transformation:

      Property Description
      Namespace Prefix Provide the namespace prefix of the payload expression to be validated.
      For example, specify the namespace prefix as SOAP_ENV.
      Namespace URI Provide the namespaceURI 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/.
    11. Click Save.
      The API is saved with the added custom extension.

    12. Invoke the API.
      The custom variables are defined and can be accessed in the subsequent policy stages.

    Custom Extension Properties

    The table lists the properties that you can specify for a custom extension.

    Request Processing Section

    The table lists the custom extension properties you can configure in the Request processing section:

    Property Description
    Payload Provide the request payload to be sent to the custom extension in one of the following ways:

    • Type the request payload in the text box.

      For details on the data objects and variables available in the Request Processing section that you can use to configure, see Data Objects and Variables Available in API Gateway.

    • Click and select one of the following and provide the required information:

      • Inline Request. Type the required payload.

      • Load from Schema. Click Browse to upload a JSON or XML schema file and click Save.
    Headers Provide the following information, if you want to configure the headers you need to send to the custom extension. By default, no headers are sent to the custom extension.

    • Select Use incoming headers to use the header content in the incoming requests from the client.

    • Provide the Header Name and the Header Value in the incoming client request that has to be processed.
    Query Parameters Provide the following information, if you want to configure query parameters you need to send to the custom extension.

    • Provide the Query Parameter Name and the Query Parameter Value in the incoming client request that has to be processed.
    For details on the data objects and variables available in the Request Processing section that you can use to configure, see Data Objects and Variables Available in API Gateway.
    Response Processing section

    The table lists the custom extension properties you can configure in the Response Processing section:

    Property Description
    Copy the entire response Select to copy the entire response received from the external call out. This response is used in the subsequent step by using request.payloador{request.payload} or {response.payload}.

    Note: Do not select this if you are using AWS Lambda custom extension with invocation type as Event as there is no response returned.
    Abort API execution in case of failure Select to abort the API execution when the external callout encounters any failures. If you do not select this option, API Gateway logs the failure and continues with the processing.
    Transformation Specify the following custom variables with a syntax to be accessed from the response of the custom extension and click Add.

    • Variable. Specifies the variable type with a syntax.

    • Value. Specifies a value with a syntax.
    For example if you provide a variable as varandthecorrespondingvalueas{var} and the corresponding value as {response[customPolicy].payload.jsonPath[.id]}, this transformation evaluates the JSON path from the custom policy response payload to get the value of the attribute id. The evaluated value is assigned to the variable var given in the Variable field. You can use the {var} syntax in the subsequent policies that support variable framework.
    For details about the data objects and variables available in the Response Processing section that you can use to configure, see Data Objects and Variables Available in API Gateway.
    Custom extension metadata This is used for XML transformation.

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

    • Namespace URI. Provide the namespace URI of the payload expression to be validated.
    Custom Extension Metadata section

    The table lists the custom extension properties you can configure in the Custom Extension Metadata section. This is applicable only for XML transformation:

    Property Description
    Namespace Prefix Provide the namespace prefix of the payload expression to be validated.
    Namespace URI Provide the namespace URI of the payload expression to be validated.

    For details about the data objects and variables that you can use to configure, see Data Objects and Variables Available in API Gateway.

    Data Objects and Variables Available in API Gateway

    The following table summarizes the data objects and variables that are available in API Gateway:

    Object/Variable type Possible values
    paramStage
    • request

    • response
    paramType
    • payload or body

    • headers

    • query

    • path

    • httpMethod

    • statusCode

    • statusMessage
    queryType
    • xpath

    • jsonPath

    • regex

    The following data objects are available in the request processing or response processing steps: - ${paramStage.paramType} You can use this syntax to access the following string variables: path, statusCode, statusMessage, httpMethod. Examples: ${request.path}, ${response.statusCode}.

    Request and Response Transformation Policies

    Transformation policy enables you to configure several transformations on the requests from the clients into a format required by the native API, or to transform the response by the native API into a format required by the client.

    The transformations include Header, Query Parameter, Path Parameter transformation, HTTP Method transformation, Payload transformation, and Advanced transformation. The transformations are applied based on the configurations provided in the transformation policies.

    When can you use transformation policies?

    You can use transformation policies:

    Pre-Requisites

    How do I transform a request using Request Transformation Policy?

    Use the Request Transformation policy to modify the contents of an incoming request such as headers, payload, query parameters, path parameters, HTTP method using the configurations given by the API Provider.

    The request transformation workflow is as follows:

    1. The API Provider configures the Request Transformation policy in the Request Processing stage of API Gateway. The API provider configures the details about when and how to transform the contents of an incoming request.

    2. The client sends the request to API Gateway.

    3. API Gateway applies the transformations configured by the API Provider and transforms the incoming request.

    4. API Gateway sends the transformed request to the native API.

    5. Native API processes the transformed request and sends the response to API Gateway.

    6. API Gateway forwards the response to the client.

    Consider a scenario where you have a legacy REST API (employeeApi) that does not adhere to the REST API standards. For example, it accepts functional information such as employee name through a header employeeName instead of accepting them through query or path parameters and you want to modify the API to REST standards.

    To configure request transformation policy:

    1. Click APIs in the title navigation bar.
      A list of available APIs appears.

    2. Select a Rest API from the list of APIs and click Edit.

    3. Select Policies > Request Processing > Request Transformation.
      The Request Transformation details page appears.

    4. In the Condition section, select OR.
      The configured transformation is applied when at least one of the conditions is satisfied.

      Note
      The condition can also be set to AND operator. The configured transformation is applied only when all the set conditions are satisfied.

    5. Click Add Condition to configure the conditions to evaluate the contents on the request.

      a. Specify the Variable. Example, Content-Type.

      b.Specify the Operator to use to relate variable and the value provided. Example, Equals.

      c. Specify the Value. Example, application/json.
      When you select the operator - Equals, the Condition checks if the Variable: Content-Type is equal to the Value: application/json.

      d. Click Add.

    6. Select Transformation Configuration > Header/Query/Path transformation.
      The Header/Query/Path transformation details page appears.

    7. In Add/Modify section, add the variable and set its value.
      Here, native API accepts employee name through header ${request.headers.employeeName} and you want the native API to accept these values through the query parameter ${request.query.name} and expose this change to the client without exposing the query parameter.

      To achieve this, set the variable and the value parameters as follows:

      a. Variable: ${request.headers.employeeName}

      b. Value: ${request.query.name}

      c. Click Add.

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

    8. In the Remove section, add ${request.query.name} to remove the query parameter from the request so that it does not reach the native API.

    9. Click Save.

    This request transformation policy configuration allows the native API to accept the header values through query parameters. The native API accepts the header values through the query parameters by transforming the query parameters to header parameters and then removing the query parameter from the incoming request.

    Request Transformation Policy Properties

    The table lists the properties that you can specify for the Request Transformation policy.

    Property 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. You can select one of the following:
      • Equals
      • Equals ignore case
      • Not equals
      • Not equals ignore case
      • Contains
      • 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>
    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.xpathForexample:{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 prefixes and URIs by clicking icon.

    How do I transform a request and its response using Transformation Policy?

    Use the Response Transformation policy to modify the contents of an outgoing response such as headers, payload, query parameters, path parameters, HTTP method using the configurations given by the API Provider.

    The response transformation workflow is as follows:

    1. The API Provider configures the Response Transformation policy in the Response Processing stage of API Gateway. The API provider configures the details about when and how to transform contents of an outgoing response.

    2. The client sends the request to API Gateway.

    3. API Gateway forwards the request to native API.

    4. Native API processes the request and sends response to API Gateway.

    5. API Gateway applies the transformations configured by the API Provider and transforms the outgoing response.

    6. API Gateway forwards the transformed response to the client.

    Consider a scenario, where a native API URL is moved permanently or temporarily, the native API sends a 301 or 302 status code, and also sends the new address in the location header. However, when API Gateway comes across the 301 or 302 status code, API Gateway reads the status code and the location header, and redirects the request to new address mentioned in the location header. API Gateway, then sends the response from the new address to the client. This is how 3xx status code is handled in API Gateway.

    In this scenario, if you do not want API Gateway to do the redirection, instead you want the clients to receive the 3xx status code, and then do the redirection. This can be achieved by using the Status Transformation policy in the Response Processing stage.

    To achieve this transformation:

    1. Change the native API to send an intermediate 2xx status code instead of 3xx status code, for request from API Gateway.

      For example, a demo service package contains a couple of REST services - source and destination.

      The REST service source is moved to a new address and it sends a 301 status along with location header. However, it sends 297 status code with the location header for requests from API Gateway. The location header contains the address for destination, which is the new address of the moved resource.

    2. Configure the API in API Gateway with a Request Transformation policy to send a request header requestOrigin with the value APIGateway. To configure the request transformation policy, perform the following steps:

      a. Click APIs in the title navigation bar.
      A list of available APIs appears.

      b. Select a Rest API from the list of APIs and click Edit.

      c. Select Policies > Request Processing > Request Transformation.
      The Request Transformation details page appears.

      d. In the Condition section, select OR.
      The configured transformation is applied when at least one of the conditions is satisfied.

      Note
      The condition can also be set to AND operator. The configured transformation is applied only when all the set conditions are satisfied.

      e. Click Add Condition to configure the conditions to evaluate the contents on the request.

      f. Specify the Variable. Example, Content-Type.

      g. Specify the Operator to use to relate variable and the value provided. Example, Equals.

      h. Specify the Value. Example, application/json.
      When you select the operator - Equals, the Condition checks if the Variable: Content-Type is equal to the Value: application/json.

      i. Click Add.

      j. Select Transformation Configuration > Header/Query/Path transformation.
      The Header/Query/Path transformation details page appears.

      k. In Add/Modify section, add the variable and set its value.
      Set the Variable and Value parameters as follows:

      l. Click Save.

      This Request Transformation policy allows the API in API Gateway to send a request header requestOrigin with the value APIGateway. This will help the native API identify the request from API Gateway and send the response code 297.

    3. Configure the API in API Gateway with the Status Transformation policy to transform the 297 status code to 301 status code. To configure the status transformation policy, perform the following steps:

      a. Click APIs in the title navigation bar.
      A list of available APIs appears.

      b. Select a Rest API from the list of APIs and click Edit.

      c. Select Policies > Response Processing > Response Transformation.
      The Response Transformation details page appears.

      d. In the Condition section, select OR.

      The configured transformation is applied when at least one of the conditions is satisfied.

      Note
      The condition can also be set to AND operator. The configured transformation is applied only when all the set conditions are satisfied.

      e. Click Add Condition to configure the conditions to evaluate the contents on the request.

      f. Specify the Variable. Example, ${response.statusCode}.

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

      g. Specify the Operator to use to relate variable and the value provided. Example, Equals.

      h. Specify the Value. Example, 297.
      When you select the operator - Equals, the Condition checks if the Variable: ${response.statusCode} is equal to the Value: 297.

      i. Click Add.

      j. Select Transformation Configuration > Status transformation.
      The Status transformation details page appears.

      k. Specify the Code and Message values that you would like in the response.
      Set the Code and Message parameters as follows:

      • Code: 301
      • Message: Moved Permanently

      l. Click Save.

    This transformation policy allows the clients to receive the 301 status code, and then redirect to the new address mentioned in location header.

    Response Transformation Policy Properties

    The table lists the properties that you can specify for the Response Transformation policy.

    Property 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 responses that comply with all the configured conditions
    • OR. This is selected by default. API Gateway transforms the 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:
      • Equals
      • Equals ignore case
      • Not equals
      • Not equals ignore case
      • Contains
      • 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.
    HeaderTransformation 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 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 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” :${response.headers.val1},
      “value2” :${response.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 response 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 you receive the response 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>
    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.xpathForexample:{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.

    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 ERRORMESSAGEwouldcontainanativeserviceprovidererrormessageorothererrormessagesthatresultfromenforcedsecurityassertions.However,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

    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.

    Aliases

    An alias in API Gateway holds stage-specific property values that can be shared by multiple policy configurations. Aliases referenced by policy configurations are substituted during runtime. Changing an alias value affects all referencing policies. Aliases are referenced through a name therefore alias names have to be unique within an API Gateway. The corresponding alias value is substituted in place of an alias name during run-time. Thus the same alias can be referred to in multiple policies and the change in a particular alias would affect all the policy properties. Aliases have optional stage information, in addition to a name and value, which allows to define stage-specific aliases in a multi-stage environment. For details about stage-specific aliases, see Asset Promotion. An alias definition without stage information applies to the API Gateway instance where the alias is defined.

    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 details, see Supported Alias And Policy Combinations.

    You can create six types of alias:

    Creating a Simple Alias

    You must have the API Gateway’s manage aliases functional privilege assigned to perform this task.

    A simple alias holds simple key property values. The name of the alias can be used in the configuration of the properties of a routing policy or an email destination for the Log Invocation, Monitor SLA, Monitor Performance, and Traffic Optimization policies.

    To create a simple alias

    1. Expand the menu options icon icon, in the title bar, and select Aliases.

    2. Click Create alias.

    3. In the Basic information section, provide the following information:

      Field Description
      Name Name of the alias.
      Type Select Simple alias.
      Description Description of the alias.
    4. Click Technical information and specify a value in the Default value field.

      Note
      You can specify multiple email addresses, if you are creating an email alias, for example, abc@gmail.com, test@gmail.com, and so on.
    5. Specify a stage, if you want the alias to be applicable to a specific stage.

    6. Click Save.

      Note
      For example, if you create a simple alias called hostname with value dev.com and in the routing policy you can specify the https://dev.com/v2 endpoint as https://hostname/v2.Atruntimeinvocationthesimplealias{hostname}/v2. At runtime invocation the simple alias {hostname} will be replaced with its value dev.com.

    Creating an Endpoint Alias

    You must have the API Gateway’s manage aliases functional privilege assigned to perform this task.

    An endpoint alias stores the endpoint value along with additional properties such as connection timeout, read timeout, whether to pass security headers or not, keystore alias, key alias, and so on.

    To create an endpoint alias

    1. Expand the menu options icon icon, in the title bar, and select Aliases.

    2. Click Create alias.

    3. In the Basic information section, provide the following information:

      Field Description
      Name Name of the alias.
      Type Select Endpoint alias.
      Description Description of the alias.
    4. Click Technical information and provide the following information:

      Field Description
      Optimization technique This is applicable only for a SOAP API. Specify the optimization technique for the SOAP request received. Select any one of the following:
      • None. This is the default value. API Gateway does not use any optimization method to parse the SOAP requests to the API.
      • MTOM. Indicates that API Gateway expects to receive a request with a Message Transmission Optimization Mechanism (MTOM) attachment and forwards the attachment to the native service.
      • SWA. Indicates that API Gateway expects to receive a SOAP with Attachment (SWA) request and forwards the attachment to the native service.
      Pass WS-Security Headers Passes the security header.
      Endpoint URI Specify the default URI or components of the URI such as service name.
      Connection timeout Specify the time interval (in seconds) after which a connection attempt times out. If the Connection timeout value is not specified, it defaults to 30. 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 Specify the time interval (in seconds) after which a socket read attempt times out. If the Read timeout value is not specified, it defaults to 30. 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.
      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.
      Stage Specif a stage, if you want the alias to be applicable to a specific stage.
    5. Click Save.

    Creating an HTTP Transport Security Alias

    You must have the API Gateway’s manage aliases functional privilege assigned to perform this task.

    An HTTP Transport security alias contains transport level security information required while accessing the native API. Transport level security that are supported in API Gateway outbound are as follows:

    To create an HTTP transport secure alias

    1. Expand the menu options icon icon, in the title bar, and select Aliases.

    2. Click Create alias.

    3. In the Basic information section, provide the following information:

      Field Description
      Name Name of the alias.
      Type Select HTTP transport security alias.
      Description Description of the alias.
    4. Click Technical information and provide the following information:

      Field Description
      Authentication scheme Specify the type of authentication you want to use while communicating with the native API.

      Select one of the following:

      • Basic. Uses basic authentication (user name and password).
      • Kerberos. Uses Kerberos authentication.
      • NTLM. Uses NTLM authentication.
      • OAuth2. Uses OAuth2 authentication.
      • JWT. Uses JWT authentication.
      For the Authentication type Basic, authenticate using the following:
      Custom credentials Specifies the values provided in the policy required to access the native API.

      Provide the following information:

      • Username. Specify a username to access the native API.
      • Password. Specify a password to access the native API.
      • Domain. Specify a domain to access the native API.
      Incoming HTTP basic auth credentials No properties required. Considers the incoming HTTP basic authentication credentials.
      For Authentication type Kerberos, authenticate using any of the following:
      Custom credentials Specifies the values provided in the policy required to obtain the Kerberos token to access the native API.
      Provide the following information:
      • Client principal. A valid client LDAP user name.
      • Client password. A valid password of the client LDAP user.
      • Service principal. A valid Service Principal Name (SPN). The specified value is used by the client to obtain a service ticket from the KDC server.
      • Service principal nameform. Specifies the format in which you want to specify the principal name of the service that is registered with the principal database. Select one of the following:
        • Username. Represents the principal name as a named user defined in LDAP used for authentication to the KDC.
        • Hostbased. Represents the principal name using the service name and the host name, where host name is the host computer.
      Delegate incoming credentials Specifies the values provided in the policy required by the API providers to select whether to delegate the incoming Kerberos token or act as a normal client.

      Provide the following information:

      • Client principal. A valid client LDAP user name.
      • Client password. A valid password of the client LDAP user.
      • Service principal. A valid Service Principal Name (SPN). The specified value is used by the client to obtain a service ticket from the KDC server.
      • Service principal nameform. Specifies the format in which you want to specify the principal name of the service that is registered with the principal database. Select one of the following:
        • Username. Represents the principal name as a named user defined in LDAP used for authentication to the KDC.
        • Hostbased. Represents the principal name using the service name and the host name, where host name is the host computer.
      Incoming HTTP basic auth credentials Specifies the incoming HTTP basic authentication credentials in the transport header of the incoming request for client principal and client password.

      Provide the following information:

      • Service principal. A valid Service Principal Name (SPN). The specified value is used by the client to obtain a service ticket from the KDC server.
      • Service principal nameform. Specifies the format in which you want to specify the principal name of the service that is registered with the principal database. Available values are:
        • Username. Represents the principal name as a named user defined in LDAP used for authentication to the KDC.
        • Hostbased. Represents the principal name using the service name and the host name, where host name is the host computer.
      Incoming kerberos credentials No properties required. Considers the incoming kerberos credentials.
      For Authentication type NTLM, authenticate using any of the following:
      Custom credentials Specifies the credentials that are required for the NTLM handshake.

      Provide the following information:

      • Username. Name of a consumer who is available in the Integration Server on which API Gateway is running.
      • Password. A valid password of the consumer.
      • Domain. The domain used by the server to authenticate the consumer.
      Incoming HTTP basic auth credentials No properties required. Considers the incoming HTTP basic authentication credentials.
      Transparent No properties required.
      For the Authentication type OAuth2, authenticate using any of the following:
      Custom credentials Specifies the OAuth2 token value that would be added as bearer token in the transport header while accessing the native API.
      Incoming OAuth token Considers the incoming OAuth token to access the native API.
      For Authentication type JWT, authenticate using any of the following:
      Incoming JWT Considers the incoming JSON web token to access the native API.
    5. Specify a stage, if you want the alias to be applicable to a specific stage.

    6. Click Save.

    Creating a SOAP Message Security Alias

    You must have the API Gateway’s manage aliases functional privilege assigned to perform this task.

    A SOAP message security alias contains message level security information that is requires to access the native API. If the native service is enforced with any WS security policy, API Gateway enforces those policies in the outbound request while accessing the native API using the configuration parameters specified in the alias.

    To create SOAP message secure alias

    1. Expand the menu options icon icon, in the title bar, and select Aliases.

    2. Click Create alias.

    3. In the Basic information section, provide the following information:

      Field Description
      Name Name of the alias.
      Type Select SOAP message secure alias.
      Description Description of the alias.
    4. Click Technical information and provide the following information:

      Field Description
      Authentication scheme Specify the type of authentication scheme you want to use to authenticate the client.

      Available values are:

      • None. Does not use any authentication types to authenticate the client.
      • WSS Username. Generates a WSS username token and sends it in the soap header to the native API.
      • Kerberos. Fetches a Kerberos token and sends it to the native API.
      • SAML. Fetches a SAML token and sends it to the native API.
      For Authentication scheme None. Does not require any properties.
      For Authentication type WSS Username, authenticate using any of the following:
      Custom credentials Specifies the values provided in the policy to be used to obtain the WSS username token to access the native API.
      Provide the following information:
      • Username. Specifies a username used to generate the WSS username token.
      • Password. Specifies the password used to generate the WSS username token.
      For Authentication type Kerberos, authenticate using any of the following:
      Custom Credentials Uses the Basic authentication credentials coming in the transport header of the incoming request for client principal and client password.
      Provide the following information:
      • Client principal. A valid client LDAP user name.
      • Client password. A valid password of the client LDAP user.
      • Service principal. A valid Service Principal Name (SPN). The specified value is used by the client to obtain a service ticket from the KDC server.
      • Service principal nameform. Specifies the format in which you want to specify the principal name of the service that is registered with the principal database. Select one of the following:
        • Username. Represents the principal name as a named user defined in LDAP used for authentication to the KDC.
        • Hostbased. Represents the principal name using the service name and the host name, where host name is the host computer.
      Delegate incoming credentials Specifies the values provided in the policy to be used by the API providers to select whether to delegate the incoming Kerberos token or act as a normal client.

      Provide the following information:

      • Client principal. A valid client LDAP user name.
      • Client password. A valid password of the client LDAP user.
      • Service principal. A valid Service Principal Name (SPN). The specified value is used by the client to obtain a service ticket from the KDC server.
      • Service principal nameform. Specifies the format in which you want to specify the principal name of the service that is registered with the principal database. Available values are:
        • Username. Represents the principal name as a named user defined in LDAP used for authentication to the KDC.
        • Hostbased. Represents the principal name using the service name and the host name, where host name is the host computer.
      Incoming HTTP basic auth credentials Specifies the incoming HTTP basic authentication credentials to access the native API.

      Provide the following information:

      • Service principal nameform. Specifies the format in which you want to specify the principal name of the service that is registered with the principal database. Select one of the following:
        • Username. Represents the principal name as a named user defined in LDAP used for authentication to the KDC.
        • Hostbased. Represents the principal name using the service name and the host name, where host name is the host computer.
      For Authentication type SAML
      SAML issuer configuration Specifies the SAML issuer configuration that is used by the API Gateway to fetch the SAML token which is then added in the SOAP header and sent to the native API.

      This field is visible and required only if you have configured a SAML issuer in Administration > Security > SAML issuer section.

      Signing configurations
      Keystore alias Specify the keystore that needs to be used by API Gateway while sending the request to the native API. A keystore is a repository of private key and its corresponding public certificate.
      Key alias The key alias is the private key that is used sign the request sent to the native API.
      Encryption configurations
      Truststore alias Select the truststore to be used by API Gateway when sending the request to the native API. Truststore is a repository that holds all the trusted public certificates.
      Certificate alias Select the certificate from the truststore that is used to encrypt the request that is sent to the native API.
      Stage Specify a stage, if you want the alias to be applicable to a specific stage.
    5. Click Save.

    Creating a webMethods Integration Server Service Alias

    You must have the API Gateway’s manage aliases functional privilege assigned to perform this task.

    A webMethods Integration Server service alias holds the IS service value. The name of the alias can be used to invoke the Invoke webMethods IS policy for request and response processing.

    To create a webMethods IS service alias

    1. Expand the menu options icon icon, in the title bar, and select User management.

    2. Click Create alias.

    3. In the Basic information section, provide the following information:

      Field Description
      Name Name of the alias.
      Type Select webMethods IS Service alias.
      Description Description of the alias.
    4. Click Technical information and provide the following information.

      Field Description
      Service name Specify the IS service name.
      Note: The IS service must be available in the Integration Server, to which the aliases are deployed.
      Comply to IS Spec (pub.apigateway.invokeISService.specifications) Select Comply to IS Spec, if you want the input and output parameters to comply to the IS Spec specified.
      Stage Specify a stage, if you want the alias to be applicable to a specific stage.
    5. Click Save.

    Creating an XSLT Transformation Alias

    You must have the API Gateway’s manage aliases functional privilege assigned to perform this task.

    An XSLT transformation alias holds a list of XSLT style sheets. The name of the alias can be used in the XSLT Transformation policies for request and response processing.

    To create a transformation alias

    1. Expand the menu options icon icon, in the title bar, and select User management.

    2. Click Create alias.

    3. In the Basic information section, provide the following information:

      Field Description
      Name Name of the alias.
      Type Select XSLT Transformation alias.
      Description Description of the alias.
    4. Click Technical information and browse and select an XSLT style sheet in the Select transformation file field.

    5. Specify a stage, if you want the alias to be applicable to a specific stage.

    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

    Global Policies

    Important
    API Gateway’s Standard Edition License does not support the functionality of Global Policies. You can create and manage global policies only using the Advanced Edition License.

    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 SOAP and REST APIs but not supported for GraphQL API.

    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.

    API Gateway provides a system global policy, Transaction logging, which is bundled 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 modify 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 one transaction log is created per destination.

    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
    • Authorize User, Identify & Authorize - These policies can be enforced to any API Type.
    • Inbound Auth - 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
    • 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
    • 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 Exporting and Importing Assets and Configurations.

    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.

    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 minds:

    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.

    API Scopes

    API definitions can be complex and span across multiple REST resources and methods, or SOAP operations for an API. To reduce the complexity of an API definition, you can define scopes and impose a set of policies on each scope to suit your requirements.

    A scope represents a logical grouping of REST resources, methods, or both, and SOAP operations in an API. You can then enforce a specific set of policies on each individual scope in the API.

    An API can have a set of declared scopes. The available scopes for an API are listed in the Scopes tab of the API details page.

    Creating an API Scope

    Scopes enable you to group a set of REST resources, methods, or both, and SOAP operations for an API.

    A scope consists of a name, description, and zero or more resources, methods, or operations. An API can have zero or more scopes.

    You can define a set of policies and configure its properties for each individual scope. These policies apply to each of the resources, methods, or operations that are associated to the scope.

    Instructions throughout the remainder of this guide use the term scope-level policy when referring to a set of policies configured for an individual scope of the API.

    Note
    Ensure that you have a unique set of resources, methods, or operations in every scope in the API.

    To create a scope

    1. Click APIs in the title navigation bar.
      A list of APIs available in API Gateway appears.

    2. Click the name of the required API.
      This opens the API details page.

    3. Click Edit.
      If the API is active, API Gateway prompts you to deactivate it.

    4. Click the Scopes tab.
      This displays a list of scopes available in the API.

    5. In the List of scopes section, click Add scope.

    6. In the Basic information section, provide the required information for each data fields that appears:

      Field Description
      Name Name of the scope. A scope name must be unique within an API.

      Note: API Gateway automatically adds the name New Scope to the Name field. You can change the name of the scope to suit your needs. But you cannot leave this field empty.
      Description Description of the scope.
    7. Applicable only for REST APIs. In the Resources and methods section, select the resources, methods, or both, you want to associate to this scope.
      When selecting a resource or method for the scope definition, you can select whether you want some or all of the methods within that resource to be selected as well.

    8. Applicable only for SOAP APIs. In the Operations section, select the operations you want to associate to this scope.

    9. Click Save.
      The scope is created and listed in the List of scopes section.

    Post-requisites:

    Viewing List of API Scopes and Scope Details

    The Scopes tab in the API details page displays a list of all available scopes in the API.

    In addition to viewing the list of scopes, you can also examine and modify the details of a scope, and delete a scope in the Scopes tab.

    To view the scope list and properties of a scope

    1. Click APIs in the title navigation bar.
      A list of APIs available in API Gateway appears.

    2. Click the name of the required API.
      This opens the API details page.

    3. Click the Scopes tab.
      This displays a list of scopes available in the API.

    4. In the List of scopes section, click the name of the scope you want to examine.

      This opens the details of the scope. The scope details appear in the following sections:

      • Basic information: This section contains a summary of basic information such as name and description of the scope.

      • Resources and methods: Applicable only for REST APIs. This section contains a collection of REST resources, methods, or both, that are associated to the scope.

      • Operations: Applicable only for SOAP APIs. This section contains a collection of SOAP operations that are associated to the scope.

    Modifying API Scope Details

    You use the Scopes tab in the API details page to examine and modify the details of a scope.

    To modify the properties of a scope

    1. Click APIs in the title navigation bar.
      A list of APIs available in API Gateway appears.

    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 Scopes tab.
      This displays a list of scopes available in the API.

    5. In the List of scopes section, click the name of the scope you want to modify.

      This opens the details of the scope. The scope details appears in the following sections:

      • Basic information: This section contains a summary of basic information such as name and description of the scope.

      • Resources and methods: Applicable only for REST APIs. This section contains a collection of REST resources, methods, or both, that are associated to the scope.

      • Operations: Applicable only for SOAP APIs. This section contains a collection of SOAP operations that are associated to the scope.

    6. Modify the basic properties, applicable resources, methods, or operations of the scope.

    7. Click Save.
      Activate the API, if it is not active, to put it into effect.

    Deleting an API Scope

    You delete a scope to remove it from the API permanently.

    When a scope is deleted from the API definition, API Gateway deletes the existing associations between the scope and the collection of resources, methods, or operations in the API. But, the collection of resources, methods, or operations continue to exist in the API.

    To delete a scope

    1. Click APIs in the title navigation bar.
      A list of all registered APIs appears.

    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 Scopes tab.
      This tab displays a list of scopes available with the API.

    5. In the List of scopes section, locate the name of the scope you want to delete.

    6. Click the Delete (icon) icon next to the scope name.

    7. Click Yes in the confirmation dialog.
      The scope is removed from the List of scopes section.

    8. Click Save to save the updated API.
      Activate the API, if it is not active, to put it into effect.

    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.

    Example - Usage Scenarios of API Scopes

    API Provider can restrict the enforcement of policies at the resource-level or method-level for a REST API, and at the operations-level for a SOAP API. This policy enforcement on the resources, methods, or operations of the API will apply in addition to the default enforcement of policies at the global-level and the user-defined enforcement of policies at the API-level.

    Consider you have a REST API, for example, PhoneStore API, with a collection of resources and methods.

    Resource Name Resource Path Supported Methods
    Resource A /phones/orders GET
    POST
    Resource B /phones/orders/{order-id} GET
    PUT
    DELETE
    Resource C /phones/orders/{order-id}/paymentdetails GET
    POST

    In the following section, we demonstrate the application of scopes and the policy enforcement using Resource C: /phones/orders/{order-id}/paymentdetails of the PhoneStore API.

    You can create scopes in the PhoneStore API, and define the individual scopes with a specific set of resources, methods, or both.

    Scope Name Applied Resource Applied Method
    PAYMENT Scope Resource C: /phones/orders/{order-id}/paymentdetails  
    WRITE Scope Resource C: /phones/orders/{order-id}/paymentdetails POST

    Assume you have an API-level policy which enforces an Identify and Authorize Application policy with HTTP Basic Authentication for the PhoneStore API. Now, you might need to have different authentication mechanisms for different methods and resources (collectively, scopes) of the PhoneStore API, depending on the level of access you need.

    For example, you might want to enforce an Inbound Authentication - Transport policy with Require HTTP Basic Authentication for the Resource C in PAYMENT Scope to enforce secured access to the data. You might also want to apply an Identify and Authorize Application policy with API Key authentication and Traffic Optimization policy (with 5 API invocations per minute), in particular, for the POST method of the Resource C in WRITE Scope to enforce a higher-level of secured access and manipulation of the REST data.

    API-level/Scope-level Policy Applied Policies
    API-level Policy Identify and Authorize policy with HTTP Basic Authentication
    Scope-level Policy for PAYMENT Scope Inbound Authentication - Transport
    Scope-level Policy for WRITE Scope Identify and Authorize policy with API Key

    Traffic Optimization

    The API Scopes definition looks like this:

    API-level / Scope-level Policy Applied Policies
    API-level Policy Identify and Authorize policy with HTTP Basic Authentication
    Policy for PAYMENT Scope Resource C: /phones/orders/{order-id}/paymentdetails   Identify and Authorize
    Policy for WRITE Scope Resource C: /phones/orders/{order-id}/paymentdetails POST Identify and Authorize policy with API Key

    Traffic Optimization

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

    1. Global Policy Enforcement

    2. Method-level Policy Enforcement (REST APIs) -OR- Operation-level Policy Enforcement (SOAP APIs)

    3. Resource-level Policy Enforcement (REST APIs)

    4. API-level Policy Enforcement

    The specific aspect of processing during the handling of an API invocation at run-time in API Gateway can be best understood with the following scenarios:

    Scenario A: Invoke GET method on the Resource C: /phones/orders/{order-id}/paymentdetails

    As per the precedence of policy enforcement, the Inbound Authentication - Transport at the resource-level and the Identify and Authorize Application policy with HTTP Basic Authentication at the API-level are enforced at run-time.

    The effective policy set enforced on the API for the GET method at run-time includes:

    Scenario B: Invoke POST method on the Resource C: /phones/orders/{order-id}/paymentdetails in WRITE Scope

    As per the precedence of policy enforcement, the Identify and Authorize Application policy with API Key at the method-level takes precedence over the Identify and Authorize Application policy with HTTP Basic Authentication at the API-level, and is enforced at run-time.

    The effective policy set enforced on the API for the POST method at run-time includes:

    Now, consider that you apply an active Global Policy that has the Identify and Authorize policy with Hostname Address for all REST APIs (including our PhoneStore API).

    Scenario C: Invoke POST method on the Resource C: /phones/orders/{order-id}/paymentdetails in WRITE Scope

    As per the precedence of policy enforcement, the Identify and Authorize policy with Hostname Address applied through the global policy takes precedence over every other Identify and Authorize Application policy that is applied at the method-level and the API-level, and is enforced at run-time.

    The effective policy set enforced on the API for the POST method at run-time includes: - Inbound Authentication - Transport

    Resolving Scope Conflicts

    When you save an API, API Gateway combines the scopes specified with the set of policies defined at the API-level, and on saving the API, API Gateway applies the policies to the API at various enforcement levels. API Gateway validates the scope list to ensure that it contains no conflicting or incompatible policies. If the list contains conflicts or inconsistencies, API Gateway prompts you with an error message.

    Consider that you modify the existing UPDATE scope to include a POST method for Resource C. The API Scopes definition now looks like this:

    API-level / Scope-level Policy Applied Policies
    API-level Policy Identify and Authorize policy with HTTP Basic Authentication
    Policy for PAYMENT Scope Resource C: /phones/orders/{order-id}/paymentdetails
    Identify and Authorize policy
    Policy for WRITE Scope Resource C: /phones/orders/{order-id}/paymentdetails
    Method:POST
    Identify and Authorize Application policy with API Key
    Traffic Optimization
    Policy for UPDATE Scope Resource C: /phones/orders/{order-id}/paymentdetails
    Method:POST
    Identify and Authorize policy with IP Address Range

    Scenario D: Save the updated PhoneStore API.

    As per the precedence of policy enforcement, the Identify and Authorize Application policy at the method-level in WRITE and UPDATE Scopes take precedence over the Identify and Authorize Application policy at the API-level. But the Identify and Authorize Application policy with the API Key and IP Address Range authentications that are applied at the method-level results in a policy conflict.

    To resolve the conflicts, you can choose one of the following workaround:

    Policy Templates

    Note
    API Gateway’s Standard Edition License does not support policy templates. You can create and manage policy templates only using the Advanced Edition License.

    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.

    Change Ownership of Assets

    Assets such as APIs and applications in API Gateway have an option where the ownership of the asset can be changed. Applications have confidential data like API key and client certificates which only the owner can view. Therefore, if the owner of an asset has to take up a different responsibility or leave the organization, no other user can view the secrets of the asset. The edit option available on the asset details page, enables the transfer of ownership of the asset to another user, so that the new owner of the asset can access or view the confidential data of the asset. API Gateway provides an option to configure an approval process for the assets’ ownership change. Approval and auditing contribute to the governance of change ownership.

    Before you begin

    Ensure that you have:

    For details on functional privileges available, see API Gateway Functional Privileges.

    The change owner approval process configured and enabled if you want to enforce an approval process for ownership changes of assets. For details on configuring the approval process, see How Do I Configure the Approval Process for Ownership Change of Assets?

    The figure depicts the workflow for changing ownership of assets:

    How Do I Change the Ownership of an API?

    This use case explains how to change the ownership of an API. You can configure an approval process for the change of ownership to take effect, if required.

    The use case starts when you have an API that requires a change of owner and ends when you successfully change the API’s ownership.

    In this example, an API petstore is owned by user1. The ownership of petstore has to be changed to user2 through an approval process.

    Before you begin

    Ensure that you have the change owner privilege.

    To change the ownership of an API

    1. Log on to API Gateway as a user with the change owner privilege.

    2. Click APIs on the title navigation bar.

    3. Click petstore.

      The API details page appears. The owner of the API petstore is user1 as displayed in the Basic information section.

    4. Click change.

    5. Select user2 from the list and click .

      The change approval process is initiated.

      Note
      If the approval flow is not configured, the owner of the API changes to user2 and a success message appears. Skip to step 8.
    6. An approval request is sent to the approver.

    7. The approver approves the request that resides in the Pending Requests section of the API Gateway UI.

      Note
      The approver can click Reject to reject the request for ownership change if the request is invalid. A reject notification is sent to the requester and the ownership of petstore remains with user1.
    8. Click Change ownership request details to view the request details. The Request details dialog box appears.

      The approval notification is sent to the requester.

    9. The owner of the API petstore is changed from user1 to user2.

    How Do I Change the Ownership of an Application?

    This use case explains how to change the ownership of an application. You can configure an approval process for the change of ownership to take effect, if required.

    The use case starts when an application requires a change of owner and ends when you successfully change the application’s ownership.

    In this example, an application App1 is owned by the teams Administrators. The ownership of App1 has to be changed to Devteam through an approval process.

    Before you begin

    Ensure that you have the change owner privilege.

    To change the ownership of an application

    1. Log on to API Gateway as a user with the change owner privilege.

    2. Click Applications on the title navigation bar.

    3. Click the required application app1.
      The application details page appears. The owner of the application app1 is user1 as displayed in the Basic information section.

    4. Click .

    5. Select Team.

    6. Select DevTeam from the list and click .
      The change approval process is initiated.

      Note
      If the approval flow is not configured, the owner of the application changes and a success message appears. Skip to step 8.
    7. An approval request is sent to the approver.

    8. The approver approves the request that resides in the Pending Requests section of the API Gateway UI.

      Note
      The approver can click Reject to reject the request for ownership change if the request is invalid. A reject notification is sent to the requester and the ownership does not change.

      Click Change ownership request details to view the request details. The Request details dialog box appears.

      The approval notification is sent to the requester.

    9. The owner of the application App1 is changed from Administrators to DevTeam.

    How Do I Change the Ownership of Multiple Assets?

    It is convenient to change the asset ownership for multiple assets with a single REST request than doing it separately for individual assets. This use case explains how to change the ownership of multiple assets by sending a REST request. You can configure an approval process, if required, for the change of ownership to take effect.

    The use case starts when multiple assets require change of owner and ends when you successfully change the ownership of the assets to another user.

    To change the ownership of multiple assets

    1. Use the following REST request to change the asset ownership to a new user:
    
    POST http://hostname/rest/apigateway/assets/owner
     
    Content-Type: application/json
        
    {
        "assetType": "*", (API/APPLICATION)
        "assetIds": ["*"],
        "currentOwner": "user1",
        "newOwner": "user2"
        
    
    }
    

    Provide the following information in the REST request:

    Example 1: If user1 owns two assets, an API petstore and application app1, and you want the ownership to be transferred to user2, send a REST request as follows:

    
        POST http://localhost:5555/rest/apigateway/assets/owner
     
        Content-Type: application/json
        
        {
        "assetType": "*", (API/APPLICATION)
        "currentOwner": "user1",
        "newOwner": "user2"
        }
        
    

    This request transfers the ownership of all the assets owned by user1 to user2.

    The change approval process is initiated.

    Example 2: user1 owns three APIs, api1, api2, and api3 and two applications, app1 and app2. If you want the ownership of api1, api2, and app1 to be transferred to user2, send a REST request as follows:

    
        POST http://localhost:5555/rest/apigateway/assets/owner
     
    
        Content-Type: application/json
        
    
        {
        "assetType": "*", (API/APPLICATION)
        "assetIds": ["apiID1, apiID2, appID1"],
        "currentOwner": "user1",
        "newOwner": "user2"
        }
        
    

    where apiID1, apiID2, and appID1 are asset IDs of api1, api2, and app1 respectively.

    The change approval process is initiated.

    Note
    If the approval flow is not configured, the ownership of the assets changes from user1 to user2. Skip to step 4.
    1. An approval request is sent to the approver. The approval request contains information of all the assets whose ownership needs to change and the new owners’ name.

    2. The approver approves the request in the Pending Requests section of the API Gateway UI. The approval notification is sent to the requester.
    3. The owner of the assets is changed from user1 to user2.

    Debugging API

    With Trace API support, you can monitor the complete life cycle of the runtime requests within API Gateway. This use case explains how to trace an API call in API Gateway. You can perform tracing for any runtime requests. Inspecting the failed runtime requests help you to debug and troubleshoot your API calls. You can trace REST, SOAP, and OData API calls only.

    On enabling the tracer for an API, you can view the list of runtime requests that invoked the API. For each request, you can view

    Important considerations when you trace an API:

    The following policies are covered as part of trace API:

    Note
    You can enable or disable tracing for an API by using the Service Management REST API. For more details, see Service Management.

    How do I enable tracing?

    This use case starts when you want to enable trace for an API and ends when you view the trace details for that API.

    Before you begin

    Ensure that you have:

    To enable tracing

    1. Click APIs in the title navigation bar.

    2. Click an API for which you want to enable the trace.
      The API details page displays the basic information, technical information, resources and methods, and specification for the selected API.

    3. Click the Enable tracing button.
      Once you have enabled the tracer, the API details page displays the warning message, This API has tracing enabled. Tracing impacts performance and storage, hence disable tracing when it is not needed.

    4. Click the Tracer tab to view the trace details.
      The Trace API page displays the Runtime events, Policies applied, and Event tracer details sections.

      Note
      When you enable tracer, API Gateway captures a large amount of data, which might impact the performance and availability of the product. Hence Software AG strongly recommends you to disable the tracer when not needed.

    How do I filter the runtime request?

    This use case starts when you want to filter the client request based on its runtime events and ends when you view the trace details of the filtered client request.

    To filter the runtime event

    1. Click the Tracer tab.
      The Trace API page displays the Runtime events , Policies applied , and Event tracer details sections.

    2. In the Runtime events section, click to filter the runtime events.
      The Apply filter pop-up window displays.

    3. To filter the runtime events, click and select the time interval using the options:

      • Quick select. Specify the time interval. Click Apply to filter the runtime events based on the time interval.
      • Commonly used. Select a commonly used time interval, and the filter is applied automatically. To view the runtime events between a time interval, click Custom range > From Date > To Date > Apply .
      • The Runtime events section displays the list of runtime events based on the applied filter.

        The runtime events are displayed using various legends to indicate the different types of requests along with their status code.

        The below table displays the legends and their description:

        Legends Description
        Successful API calls
        Failed API calls due to client-side errors
        Failed API calls due to Server-side errors
        Redirection calls
        Informational calls

    How do I view the trace details?

    This use case starts when you want to view the stage-wise and policy-wise trace details about the selected client request and ends when you view the trace details at the policy level.

    Before you begin

    Ensure that you have:

    To view the trace details

    1. In the Runtime events section, click the client request for which you want to view the trace details.
      The Trace API page refreshes and populates data in the Policies applied and Event tracer details sections. By default, the Event tracer details section displays the General Information, API request and response, and Server logs sections. Under the API request and response section, you have the following sub-sections:

      • Request sent by client. Displays the request headers and request body sent by the client to API Gateway.
      • Response sent to client. Displays the response headers and response body sent to the client from API Gateway.
      • Request sent to native service. Displays the request headers and request body sent to the native API from API Gateway.
      • Response sent by native service. Displays the response headers and response body sent by the native API to API Gateway.
      Note
      If the request and response body has streaming content, the tracer does not capture the streaming content even if you have enabled the tracer.

    2. In the Policies applied section, click the stage name for which you want to view the trace details.

      The Trace API page refreshes the Event tracer details section with the stage_ name stage execution status section displaying the status and response time of the stage and policies that are enforced during API invocation.

      Note
      • In the Policies applied section, if no policies is enforced in a stage during the invocation then that stage is disabled. In this use case, Error Handling stage is disabled.
      • The Status column indicates that whether the corresponding policy is invoked or not. If the Status column displays , it indicates that the corresponding policy is enforced successfully during invocation but it does not mean that the conditions specified in the policy are matched. You can click the respective policy to know more details on how the conditions were applied during invocation.
    3. In the Policies applied section, click the policy name for which you want to view the trace details.
      The Trace API page refreshes the Event tracer details sections with the policy_name policy config/input/output section displaying the configuration details, values that were passed as input before the enforcement of the policies and values that were transformed at the end of the policy enforcement, conditions and transformations that were applied and performed at the time of invocation, and payloads.

      Note
      The template of the policy_name policy config/input/output section varies based on the policy.

    How do I inspect failed runtime requests using tracer?

    This use case starts when you want to inspect the failed runtime request and ends when you debug and troubleshoot the failed API requests.

    To inspect the failed runtime request

    1. In the Runtime events section, click the client request for which you want to inspect the trace details.
      The Trace API page refreshes and populates data in the Policies applied and Event tracer details sections. By default, the Event tracer details section displays the General Information, API request and response, and Server logs sections. Under the API request and response section, you have the following sub-sections:

      • Request sent by client. Displays the request headers and request body sent by the client to API Gateway.
      • Response sent to client. Displays the response headers and response body sent to the client from API Gateway.
      • Request sent to native service. Displays the request headers and request body sent to the native API from API Gateway.
      • Response sent by native service. Displays the response headers and response body sent by the native API to API Gateway.
      Note
      If the request and response body has streaming content, the tracer does not capture the streaming content even if you have enabled the tracer.

    2. In the Policies applied section, click the stage name highlighted in red for which you want to inspect the trace details.

      The Trace API page refreshes the Event tracer details section with the stage_ name stage execution status section displaying the status and response time of the stage and policies that failed during API invocation.

      Note
      In the Policies applied section, if no policies in a stage is enforced during the invocation then that stage is disabled. In this use case, Response Processing stage is disabled and it is not enforced as the API invocation fails in the Routing stage. The Error Handling stage was enforced in order to handle the Routing stage failure.
    3. In the Policies applied section, click the policy name request highlighted in red for which you want to inspect the trace details.
      The Trace API page refreshes the Event tracer details sections with the policy_name policy config/input/output section displaying the configuration details, values that are passed during the enforcement of that policy, transformation conditions, and payloads. It also highlights the exact location where the policy invocation failed along with the failure reason.

    Note
    The template of the policy_name policy config/input/output section varies based on the policy.

    How do I import runtime requests?

    This use case starts when you want to import the client request from any other API Gateway instance to your API Gateway instance and ends when you view the trace details for the imported request.

    Before you begin

    Ensure that the imported request’s API ID matches with the API ID to which you import the request. The API type must also match with the API to which you import the archived request. If the imported request’s API ID or API type doesn’t match with the existing API, API Gateway rejects the import request.

    To import the runtime request

    1. Click the Tracer tab.
      The Trace API page displays the Runtime events, Policies applied, and Event tracer details sections.

    2. In the Runtime events section, click to import the archived runtime request.
      The Import and view events pop-up window displays.

    3. Browse the runtime request file that you want to import.

      Note
      Make sure the file that you import does not exceed 50 MB.
    4. Click the View button.
      The imported request gets displayed in the Runtime events section.

    How do I export or download runtime requests?

    This use case starts when you want to export the client request from your API Gateway instance to your local machine and ends when you import the request in another API Gateway instance.

    To export the runtime request

    1. Click the Tracer tab.
      The Trace API page displays the Runtime events, Policies applied, and Event tracer details sections.

    2. In the Runtime events section, select the runtime event that you want to export.

    Note
    The Runtime events section lists only 20 runtime events per page. When you click Select all per page check box, all the runtime events of the API do not get selected. Instead, the 20 runtime events that are listed in that particular page gets selected.
    1. Click to export the runtime request. The selected request is downloaded to your local machine in a predefined location.





    API Mashups

    Servers that provide an API may expose a vast set of functionality. However, each individual service in the API usually provides a very specific functionality. While this is usually effective, sometimes it is useful or required to consolidate a few services and expose them as a single service. In other situations, you might want to extend a service with the functionality provided by an external API. API mashups address these requirements for grouping services and exposing them as a single service.

    Note
    Currently, API Gateway supports API mashups for REST APIs only. You can define a mashup only in a REST API and only REST APIs can be included in the mashup.

    The APIs that are included in an API mashup (participating APIs) can be connected to each other in the following ways:

    Usage scenario: API chaining

    Assume an API that provides information about courses offered by different universities in a given location. This API provides a service that returns the list of universities for a given course name and postal code. This service could be:

    
    GET /universities?course=medicine&postalcode=600012
    

    The provider of the API wants to extend this API for use in mobile applications that have access to users’ location. As mobile applications can access a user’s location in terms of longitude and latitude, this involves first retrieving the postal code for the users’ current location and then passing that information to the existing API.

    Suppose there is a publically available API that returns the postal code based on longitude and latitude values. This service could be:

    
    GET /postalcode?lat=331&long=22324321
    

    If this public API meets other requirements, such as security, performance, and usage limits, it can be utilized to deliver the required functionality.

    Using an API mashup, you can create and expose a single service that calls both services: the external service that returns the postal code and the existing service that provides the list of universities. The resulting service could be:

    
    GET /universities?course=medicine&lat=331&long=22324321
    

    Usage scenario: API aggregation

    Assume an IT services provider that provides hosting and cloud services to its customers. Users can create accounts for the different types of services that they need to use: bare metal servers, Virtual Private Servers, platforms as a service, and so on. A customer has multiple types of accounts. The statement for each type of account is returned by a different API. The API provider wants to provide a single API that consolidates the statements of a given customer and returns a single response with all the information.

    Key Features of a REST API Mashup

    Considerations for Creating an API Mashup

    Structure of an API Mashup

    An API mashup consists of one or more mashup steps, and each step invokes an API. A mashup step defines the request for the API that it invokes. A step can use the data objects provided by API Gateway to access data in the initial request sent to the operation that has the mashup and any of the previous steps.

    The following table summarizes the data objects and variables that are available in API Gateway:

    Object/Variable Type Possible values
    paramStage
    • request
    • response
    paramType
    • payload or body
    • headers
    • query
    • path
    • httpMethod
    • statusCode
    • statusMessage
    queryType
    • xpath
    • jsonPath
    • regex

    The following data objects are available to a mashup step:

    Note
    Data objects from any of the steps of the mashup can also be accessed by response processing policies and error processing policies of the API that contains the mashup.

    Creating an API Mashup

    To create a mashup you require:

    To create a mashup in a REST API

    1. Click APIs in the title navigation bar. A list of all registered APIs appears.

    2. Click the required API.
      The API details page appears.

    3. Click Edit.

    4. Click Mashups.
      The Mashups tab appears. It displays the resources in the API and their methods on the left and an empty (Default routing) routing diagram.

      Note
      If the API does not have any mashup, the Mashup tab displays the list of resources only in the Edit mode; the tab is empty in the view mode.
    5. In the List of resources, click the resource in which you want to include the mashup.
      The resource tab expands and the methods included in the resource are displayed.

    6. Click the toggle button to enable the method in which you want to create the mashup.

      Note
      If you use the toggle button and disable a method that has a mashup, the mashup definition for that method is immediately cleared.
    7. Click Add invoke to add a mashup step.

      a. Connect the step to Start. The Start and Stop terminators and all steps have connection points that you can connect to the other steps and terminators.
      To select a connection point and connect it to another connection point:

      • Hover the mouse over the top or bottom of the step or terminator till the connection point is highlighted

      • Click the connection point and drag to the other step or terminator.

      b. Configure the step properties as desired.
      The Mashup Routing panel that appears on the right side of the mashup canvas displays the properties for the selected step. You can configure the following properties using the Mashup Routing panel:

      Section Field Description
      Mashup step name Provide a name for the mashup step that is unique within the mashup.
      API Endpoint The API endpoint that you want to invoke in the mashup step. The API must be published on the current API Gateway instance.
      API Gateway API The endpoint of the API that you want to use. You can type a few letters and select from the autocomplete list.
      Resource The resource in the API that you want to use. You can type a few letters and select a resource from the autocomplete list.
      Method The specific method of the resource that you want to invoke.
      Execute outbound authentication policy Select if you want the outbound security policies of the participating API to be enforced in the context of an API mashup.
      Headers
      Use incoming Headers Select to use the headers in the incoming request.
      Custom Headers Custom headers that you can add in addition or instead of the incoming headers. Each custom header must have the following fields:

      • Header Name

      • Header Value
      Query Parameters Provide the following values:

      • Query Parameter Name

      • Query Parameter Value
      Path Parameters Provide the following values:

      • Path Parameter Name

      • Path Parameter Value
      Payload Type the Payload.
      XSLT Document Click Add xslt document and select the XSLT file for transforming the payload. Provide the following values:

      • XSLT File

      • Feature Name

      • Feature value

      • For information about transforming the payload using XSLT, see Request Transformation.
      XSLT Transformation alias Click Add xslt transformation alias and select an existing XSLT transformation alias.
      Transformation Metadata
      Namespace Provide the following values:

      Custom Pipeline Variables You can use custom pipeline variables to hold values that need to be used in another step of the API mashup. Provide the following values:

      • Name

      • Value

      • For more information, see Structure of an API Mashup above.
      Note
      In several fields, such as Header Value within custom headers, Query Parameter Value, and Path Parameter Value, you can use values from previous steps and other data using the variable and alias framework provided by API Gateway. For more information, For more information, see Structure of an API Mashup above.
    8. Click Add aggregator to add an aggregator step.

      Note
      You can also add an aggregator step by connecting two invocation steps to the same previous step. An aggregator step is automatically added after the steps when you connect the second step to the same previous step.
    9. If you have added the aggregator by clicking Add aggregator, add the following connections:

      a. Connect the steps that need to be aggregated to the aggregator step.

      b. Connect the aggregator step to the next step.

    10. To add additional steps to the aggregated block, complete the following steps:

      a. To add a new step to the aggregated block, click Add invoke and connect the new step to the same previous step.
      You can configure the properties of the new step immediately or later. For details on configuring the step properties, see step 7.

      b. To add an existing step to the aggregated block, delete the connections of the step, if any and then connect the step to the previous step for the aggregated block and the aggregator step.

    11. Click the mashup step and configure the properties of the mashup step as desired.
      You can configure the mashup step properties using the Mashup Aggregator action panel that appears on the right side of the mashup canvas when you click the aggregator step. You can configure the following properties using the Mashup Aggregator action panel:

      Section Field Description
      Headers
      Use incoming Headers Select to use the headers in the incoming request.
      Custom Headers Custom headers that you can add in addition or instead of the incoming headers. Each custom header must have the following fields:

      • Header Name

      • Header Value
      Query Parameters Provide the following values:

      • Query Parameter Name

      • Query Parameter Value
      Path Parameters Provide the following values:

      • Path Parameter Name

      • Path Parameter Value
      Payload Type the Payload.
      XSLT Document Click Add xslt document and select the XSLT file for transforming the payload. Provide the following values:

      • XSLT File

      • Feature Name

      • Feature value
      XSLT Transformation alias Click Add xslt transformation alias and select an existing XSLT transformation alias.
      Transformation Metadata
      Namespace Provide the following values:
      • Namespace Prefix
      • Namespace URI
      Custom Pipeline Variables You can use custom pipeline variables to hold values that need to be used in another step of the API mashup. Provide the following values:
      • Name
      • Value

      • For more information, see Structure of an API Mashup above.
      Mashup Response Transformation
      • Select Aggregate response
      • Payload
      Note
      In several fields, such as Header Value within custom headers, Query Parameter Value, and Path Parameter Value, you can use values from previous steps and other data using the variable and alias framework provided by API Gateway. For more information, see Structure of an API Mashup above.
    12. Add, configure, and connect additional API invocation steps and API aggregator steps as desired.

    13. Click Save.
      The mashup is created for the selected method.

    Note
    You must activate the API to make the mashup available to client applications. For more information about activating an API, see Activating an API.

    SOAP to REST Transformation

    SOAP APIs are commonly used to expose data within enterprises. With the rapid adoption of the REST APIs, API providers must be able to provide RESTful interfaces to their existing SOAP APIs instead of creating new REST APIs. Using the API Gateway SOAP to REST transformation feature, the API provider can either expose the parts of the SOAP API or expose the complete SOAP API with RESTful interface. API Gateway allows you to customize the way the SOAP operations are exposed as REST resources. Additionally, the Swagger or RAML definitions can be generated for these REST interfaces.

    Note
    You must have the API Gateway’s manage APIs or activate/deactivate APIs functional privilege assigned to perform this task.

    Activating SOAP to Rest Transformation

    You must have the API Gateway’s manage APIs functional privilege assigned to perform this task.

    To activate SOAP to REST transformation for a SOAP operation

    1. Click APIs in the title navigation bar.

    2. Select the required API from the list of available APIs.

      The API details page for the selected API appears.

    3. Click Edit.

    4. Click REST transformation.

      A list of SOAP operations already exposed to the consumers as well as to be transformed from SOAP to REST appears. By default, all the SOAP operations are in inactive state.

    5. Click icon to activate the SOAP to REST transformation for the SOAP operations.
      Alternatively, you can activate the SOAP to REST transformation for multiple SOAP operations simultaneously by clicking the Transform all operations activation toggle button.

    6. Select the operation to edit the SOAP operations.

    7. In the Transformation Configuration section, configure the following settings:

      • Use Schema for XML to JSON transformation If you select this checkbox, the XML schema (present in the WSDL) defines the data type of the entity. The data type can either be String, Int, Double, Float, or Boolean. In the response from the native server, if an entity is of a different data type other than the ones defined in the XML schema, API Gateway returns it is as a String data type and not an error.
        If you do not select this checkbox, API Gateway does not honor the XML schema during transformation. Instead, API Gateway derives the data type of entities based on the native service response.
        By default, this checkbox is not selected for any SOAP API. If you have migrated your APIs from another instance of API Gateway , the value of this checkbox will depend on the value of the Extended property pg.soapToRest.typeConvertorEnabled in the source API Gateway of the migrated APIs. The pg.soapToRest.typeConvertorEnabled property specifies whether the key values in a SOAP request must be converted to their primitive type when a SOAP API is transformed to REST API.
        Note: Date and Enumeration data types are also considered to be strings. When API Gateway cannot determine the data type of any value, it considers the data type to be a string.

      • Use default values from schema If you select this checkbox, API Gateway considers the default values provided in the XML schema, if there are no values present in a request or response. If the request or response has some value, this value overrides the default value from XML schema.
        If you do not select this checkbox, API Gateway does not consider the default values present in the XML schema even if there are no values present in the request or response.

      • Remove operation name in response
        If you select this checkbox, the root node is not passed as a part of SOAP to REST response and only the JSON is passed. Root node is generally the SOAP operation name or SOAP operation response name, present in the XML schema. This check box is applicable only to JSON responses.
        If you do not select this checkbox, JSON response is accompanied by the root node. By default, this check box is not selected for any SOAP API.
    8. Click Save.

      The API details page for the selected API appears.

    9. Click REST transformation.

      A list of REST resources for the SOAP operations appears. Click on each resource to view the details that are already available as REST definitions.

    Modifying the REST Definitions for SOAP Operations

    You must have the API Gateway’s manage APIs functional privilege assigned to perform this task.

    To modify the REST definitions for SOAP operation

    1. Click APIs in the title navigation bar.

    2. Select the required API from the list of available APIs.
      The API details page for the selected API appears.

    3. Click Edit.

    4. Click REST transformation.
      A list of SOAP operations already exposed to the consumers as well as to be transformed from SOAP to REST appears.

    5. Click icon to provide the Resource name and Resource path.
      Alternatively, you can activate the SOAP to REST transformation for multiple SOAP operations simultaneously by clicking the Transform all operations activation toggle button.

    6. Select the operation to edit the SOAP operations.

    7. Provide the following information:

      Field Description
      Resource name Name of the resource. The existing name of the SOAP operation automatically appears, you can modify this name.
      Resource path Path of the resource. The existing path of the SOAP operation automatically appears, you can modify this path.
    8. Click + Add Parameter and provide the following information to add the required resource level parameters:

      Field Description
      Name Name of the parameter.
      Description Description of the parameter.
      Type Specifies the parameter type. Available values - Path, Query-string.
      Data type Specifies the data type. Available values - String, Date, Date time, Integer, Double, Boolean.
      Required Specifies the parameter is required if selected.
      Repeat Applicable to parameters of type query. The query parameter value can take comma separated array values.
      Value Specifies the possible value.
      XPath XPath. Specifies how the request parameter must be mapped to the SOAP payload that is sent to the native SOAP service. For example,
      /soapenv:Envelope/soapenv:Body/axis:sayHello/axis:name, or //axis:name (If the SOAP request has only one element such as name).
      Namespace prefix Specifies the namespace prefix of the element that appears in the XPath.
      Namespace URI Specifies the namespace URI for the XPath element. You can add more namespace prefixes and namespace URIs by clicking .

      You can add more parameters by clicking icon.

    9. Select one of the available methods: GET, POST, PUT, or DELETE.
      By default, POST is selected. By default, API Gateway generates the sample JSON request and response based on the XML schema definitions of the SOAP API. Additionally, you can provide a schema and modify the generated sample.

    10. Click Add Request and provide the schema and a sample for the content-type.

    11. Click Add Response and select the status code from the drop-down and provide a description for the status code selected.
      Additionally, to add a content-type to the status code selected, click the status code to which you want to add a content-type and select the Content type. Provide a schema and a sample for the content-type selected. By default, status code 200 is automatically generated by the system.

    12. Click REST transformation.
      A list of SOAP operations already exposed to the consumers as well as to be transformed from SOAP to REST appears. By default, all the SOAP operations are in inactive state.

    13. Click icon to activate the SOAP to REST transformation for the SOAP operations.
      Alternatively, you can activate the SOAP to REST transformation for multiple SOAP operations simultaneously by clicking the Transform all operations activation toggle button.

    14. Select the operation to edit the SOAP operations.

    15. Click Save.
      The API details page for the selected API appears.

    16. Click REST transformation.
      A list of REST resources for the SOAP operations appears. Click on each resource to view the details that are already available as REST definitions.

    17. Click Save.

    Supported Content-types and Accept Headers

    The following table specifies the content-type available for the HTTP methods:

    HTTP Method Content-types Accept Headers
    GET application/x-www-form-urlencoded application/json
    application/xml or text/xm
    multipart/form-data or multipart/mixed
    POST application/json
    application/xml or text/xm
    multipart/form-data or multipart/mixed
    application/x-www-form-urlencoded
    application/json
    application/xml or text/xm
    multipart/form-data or multipart/mixed
    PUT application/json
    application/xml or text/xm
    multipart/form-data or multipart/mixed
    application/x-www-form-urlencoded
    application/json
    application/xml or text/xm
    multipart/form-data or multipart/mixed
    DELETE application/x-www-form-urlencoded application/json
    application/xml or text/xm
    multipart/form-data or multipart/mixed
    Note
    If a content-type is not specified, then the request verifies the value of the Set Media Type parameter. If the value of the Set Media Type parameter is not defined, then by default, for POST and PUT HTTP methods, the application/json content-type is used. Whereas for GET and DELETE HTTP methods, the application/x-www-form-urlencoded content-type is used.

    REST API Endpoints

    After providing the information required for the SOAP to REST transformation and activating the API, the API can be invoked as either SOAP or REST API.

    The REST transformation of the SOAP API does not change the API name. The only change to the SOAP invocation is that the <resource-path-for-the-operation> is appended:

    /ws/<API-NAME>/<version-number>/<resource-path-for-the-resource>

    Note
    The REST-enabled SOAP API cannot be invoked using the /rest directive.

    Samples for REST Request

    application/json

    The following table provides the samples of the REST request for the application/json content-type application and the equivalent SOAP request after transformation from REST to SOAP:

      Request Equivalent SOAP Request
    Consists of only one element (qualified namespaces)
    {
     "name":"user1"
    }
    <soapenv:Envelope xmlns:soapenv=
    "http://schemas.xmlsoap.org/soap/envelope/"
     xmlns:axis="http://ws.apache.org/axis2">
     <soapenv:Body>
     <axis:sayHello>
     <axis:name>user1/axis:name>
     </axis:sayHello>
     </soapenv:Body>
    </soapenv:Envelope>
    Consists of only one element (non-qualified namespaces)
    {
     "name":"user1"
    }
    <soapenv:Envelope xmlns:soapenv=
    "http://schemas.xmlsoap.org/soap/envelope/"
     xmlns:axis="http://ws.apache.org/axis2">
     <soapenv:Body>
     <axis:sayHello>
     <name>user1</name>
     </axis:sayHello>
     </soapenv:Body>
    </soapenv:Envelope>
    Consists of multiple elements
    {
     "a":"1",
     "b" : 2
    }
    <soapenv:Envelope xmlns:soapenv=
    "http://schemas.xmlsoap.org/soap/envelope/">
     <soapenv:Body>
     <addInts>
     <a>1</a><b>2</b>
     </addInts>
     </soapenv:Body>
    </soapenv:Envelope>
    

    application/xml and text/xml

    The following table provides the samples of the REST request for the application/xml and text/xml content-type application and the equivalent SOAP request after transformation from REST to SOAP:

      Request Equivalent SOAP Request
    Consists of only one element and namespace added by the client
    <axis:name xmlns:
    axis=
    "http://ws.apache.org/axis2"
    >user1</axis:name>
    <soapenv:Envelope xmlns:soapenv=
    "http://schemas.xmlsoap.org/soap/envelope/"
     xmlns:axis="http://ws.apache.org/axis2">
     <soapenv:Body>
     <axis:sayHello>
     <axis:name>user1</axis:name>
     </axis:sayHello>
     </soapenv:Body>
    </soapenv:Envelope>
    Consists of only one element and client does not send the Namespace
    <someOtherNamespace
    :name xmlns:toMed=
    "http:
    //someOtherNamespace"
    >user1
    </someOtherNamespace
    :name>
    <soapenv:Envelope xmlns:soapenv=
    "http://schemas.xmlsoap.org/soap/envelope/"
     xmlns:axis="http://ws.apache.org/axis2">
     <soapenv:Body>
     <axis:sayHello>
     <axis:name>user1</axis:name>
     </axis:sayHello>
     </soapenv:Body>
    </soapenv:Envelope>
    Consists of only one element and the client sends a different namespace to API Gateway
    <toMed:name xmlns:
    toMed="http://tOMed"
    >user1</toMed:name>
    <soapenv:Envelope xmlns:soapenv=
    "http://schemas.xmlsoap.org/soap/envelope/"
     xmlns:axis="http://ws.apache.org/axis2">
     <soapenv:Body>
     <axis:sayHello>
     <axis:name>user1</axis:name>
     </axis:sayHello>
     </soapenv:Body>
    </soapenv:Envelope>
    
    Multiple XML elements
    <addInts>
    <a>2</a>
    <b>3</b>
    </addInts>
    
    <soapenv:Envelope xmlns:soapenv=
    "http://schemas.xmlsoap.org/soap/envelope/">
     <soapenv:Body>
     <addInts>
    <a>2</a><b>3</b>
    </addInts>
     </soapenv:Body>
    </soapenv:Envelope>
    

    Path and Query Parameters

    The following table provides the samples of the REST request having path and query parameters and the equivalent SOAP request after transformation from REST to SOAP:

    <
      Request Equivalent SOAP Request
    Simple query or path parameter
    /ws/CalcService/
    add/{num1}

    or

    /ws/CalcService/
    add?num1=10
    <ws:addInts
    xmlns:ws="http:test">
    <num1>10</num1></ws:addInts>s
    Multiple query or path parameters
    /ws/CalcService/
    add/{num1}/{num2}

    or

    /ws/CalcService/
    add?num1=10&num2=3

    or

    /ws/CalcService/
    add/{num1}&num2=3
    <ws:addInts
    xmlns:ws="http:test">
    <num1></num1><num2></num2>
    </ws:addInts>
    Hierarchical elements
    /ws/CalcService/add/{num1}/anotherNumber/{num2}
    
    /ws/CalcService/
    add/{num1}/
    anotherNumber/{num2}
    <ws:addInts
    xmlns:ws="http:test">
    <num1></num1> <num2></
    num2></ws:addInts>
    

    multipart/form-data

    If you send the multipart/form-data content-type as the REST request, then you need to optimize the method to be used. This optimization is based on the value specified in the SOAP Optimization Method parameter available in Routing policy. The default optimization type is Message Transmission Optimization Mechanism (MTOM). For example, API Gateway converts REST requests with multipart/form-data and multipart/mixed types as follows:

    1. The Multipurpose Internet Mail Extensions (MIME) parts that have a content ID or name that match the elements of type base64Binary or hexBinary in the schema are added as attachments to the outbound request.

    2. Parts other than the content ID or name types are converted into XML depending on the content-type of the MIME part. The application/xml and application/json content-types are converted. If API Gateway is unable to process the MIME part, it wraps the MIME part inside an XML element with the name of the content ID.

    Limitations

    The following limitations apply when you perform a SOAP to REST transformation:

    API First Implementation

    APIs form the nerve center of software applications. So, it is very important for the providers to be clear about what they would provide and consumers to be clear about what they want to consume. Better understanding of APIs guarantee an excellent output. API First is all about the establishment of a common agreement between the providers and consumers. Thus, this design helps both the parties to be on the same page.

    When adapting API First approach, API developers start the API development with the API contract and work on the implementation part at a later stage. This approach of prioritizing the API design over its implementation is beneficial to both, providers and consumers.

    In conventional scenarios, providers expose APIs to their consumers only after the API is implemented. Consumers test the API and let the providers know their feedback about the API. Providers must then revisit the API to incorporate the feedback received from their consumers. You can optimize this process by adapting API First design.

    When following API First approach, consumer does not have to wait for the provider to implement the API, they can proceed with their application development using the exposed API. The implementation status of API does not have an impact on consumers as they receive the designated responses for their requests through the mocked API. So, the API development and the application development can take place at the same time.

    Once the provider implements the API, the end-point is updated to divert the invocations to the actual implementation instead of mocked response. The provider can then disable mocking.

    The following diagram explains the flow of API development as per the API First design:

    As per the API First design, providers expose their API to consumers when the development is underway.

    API First Design using API Gateway

    Starting API Gateway 10.5, the application provides seamless support for API First approach for your APIs.

    Using API Gateway, you can define API contract for the APIs and download provider specification for the APIs that you create. As a provider, you would not want to expose all resources and methods of an API to consumers. The API Contract given to the consumer has only the part of API exposed to the consumer whereas the provider specification comprises of the complete specification. This is useful for providers to implement the API.

    You can enable mocking and activate the API for consumption. The mocked version of API returns respective responses for the consumer requests. This ensures the required end-user experience to the consumers.

    When the API is ready to be implemented, you can implement your APIs in Integration Server or any other implementation server. If you are using Integration Server, you can add the required Integration Server instance in API Gateway. You can add multiple Integration Server instances and publish your API to the required instance. If you are using Integration Server, you can send the API contract from API Gateway. Else, the API contract has to be retrieved from API Gateway.

    After implementation, you can update the actual implementation end-point to API Gateway. This step is mandatory to disable API mocking and divert the invocations to the actual end-point.

    The following workflow shows the high-level workflow of API First implementation approach using API Gateway:

    API First Implementation using Integration Server

    This use case explains the steps involved in adapting API First from Integration Server. When an API created in API Gateway is implemented in Integration Server, then the API Contract is sent from API Gateway to Integration Server.

    The use case starts when you create an API in API Gateway and ends when you communicate the API implementation endpoint to API Gateway.

    In this example, the APIFirst API is created in API Gateway and implemented in the Integration Server instance, IS1 that is configured in API Gateway.

    Before you begin

    To adapt API First design using Integration Server

    1. Log on to API Gateway.

    2. Click APIs in the title navigation bar.
      A list of all existing APIs appears.

    3. Click Create API to create an API with required API documentation.

    4. Click Policies and define required policies for the API.

    5. Click Enable Mockingto mock and generate API mock responses. This step enables the API to send responses to the requests received from consumers.

    6. From the APIs page, click Publish for the APIFirst API.
      The Publish API dialog box appears.

    7. Select Integration Servers.
      The list of configured Integration Servers instances appears.

    8. Select the IS1 instance from the list.

    9. In the Package Name and Folder Name fields, provide the package name and folder name of the IS instance in which the API must be implemented.
      The API along with the API contract is published to Integration Server.

    10. After implementing the API in Integration Server, invoke the REST end-point to communicate API implemented endpoint to API Gateway:

    
         PUT http://<API Gateway hostname>/rest/apigateway/apis/{apiId}/implementation
      {
        
         "maturityState": "string",
         "nativeBaseURLs": [
         "string"
         ]
         }   
         
    

    You can provide required values for the parameters in the above command. For information on parameters, see List of Parameters used in API Implementation.

    Example:

    
         PUT http://10.2.151.149:5555/rest/apigateway/apis/
      94dfd243-dd54-4d7e-8ba5-396ffaf6fe4e/implementation
         {
         "nativeBaseURLs":["https://10.2.35.125:5556/ws/srvs:Calculator/
         CalculatorHttpSoap11Endpoint",
         "http://10.2.151.149:5555/ws/srvs:Calculator/CalculatorHttpSoap11Endpoint"],
         "maturityStatus" : "Implemented"
         }
         
    

    As a result of the REST call, the mocking of the API is disabled and the consumers requests are directed to the actual implementation.

    API First Implementation using a Third-party Server

    This use case explains the steps involved in adapting API First approach using a third-party implementation server.

    The use case starts when you create an API in API Gateway and ends when you communicate the API implementation endpoint to API Gateway.

    Before you begin

    To adapt API First design using a third-party implementation server

    1. Log on to API Gateway.

    2. Click APIs in the title navigation bar. A list of all existing APIs appears.

    3. Click Create API to create an API with required API documentation.

    4. Click Policies and define required policies for the API.

    5. Click Enable Mocking to mock and generate API mock responses.

    6. Using an external REST client such as Postman or SoapUI, run the below command to search for the API in API Gateway for implementation:

    
        POST http://<API Gateway hostname>/rest/apigateway/search
     {
        "types" : ["api"],
        "scope" : [
        {
        "attributeName" : "maturityState",
        "keyword" : "ToBeImplemented"
        }
        ]
        }
        
    

    The maturityState parameter in the above command is used search for APIs based on their maturity state. In this use case, we must search for APIs that are to be implemented. Hence, we can provide the ToBeImplemented value for the parameter. This command returns the list of APIs that are yet to be implemented.

    7. Using the API Id of the API that you want to implement, run the following command to retrieve the API contract from API Gateway:

    
        GET http://<hostname>/rest/apigateway/apis/{apiId}/
     providerspecification?format=swagger
        
    
    The value for the format parameter can be swagger, raml, or openapi for REST APIs; and wsdl for SOAP APIs.
    Note
    You can search for an API based on its maturity status in API Gateway using the following command:
    
        POST http://<API Gateway hostname>/rest/apigateway/search
     {
        "types" : ["api"],
        "scope" : [
        {
        "attributeName" : "maturityState",
        "keyword" : "ToBeImplemented"
        }
        ]
        }
        
    
    8. Implement the API in the required implementation server.

    9. After implementation, invoke the REST end-point to communicate API implemented endpoint to API Gateway:
    
        PUT http://<API Gateway hostname>/rest/apigateway/apis/{apiId}/implementation
     {
        
        "maturityState": "string",
        "nativeBaseURLs": [
        "string"
        ]
        }
        
    

    You can provide required values for the parameters in the above command. For information on parameters, see List of Parameters used in API Implementation.

    Example:

    
        PUT http://10.2.151.149:5555/rest/apigateway/apis/
     94dfd243-dd54-4d7e-8ba5-396ffaf6fe4e/implementation
        {
        "nativeBaseURLs":["https://10.2.35.125:5556/ws/srvs:Calculator/
        CalculatorHttpSoap11Endpoint",
        "http://10.2.151.149:5555/ws/srvs:Calculator/CalculatorHttpSoap11Endpoint"],
        "maturityStatus" : "Implemented"
        }
        
    

    As an outcome of the REST call, the mocking of the API is disabled and API Gateway starts requests for the actual implementation.

    List of Parameters used in API Implementation

    The following are some of the parameters used during API implementation:

    Parameter Purpose
    nativeBaseURLs Endpoint URLs of the native service. This parameter is mandatory to route the requests to this implemented API. The existing endpoint values of the routing policies of the API are replaced with the URLs given against this parameter. You can provide multiple HTTP and HTTPS URLs for this parameter. The URLs that you provide for this parameter appears under the Native endpoint(s) section in the Technical information page of API Gateway. The first URL among the list of URLs is used in the routing policies by this update call. If you want to use any other URL in the routing policies, you can update the API policies accordingly.
    maturityState Indicates the maturity state of APIs. You can use this parameter to search for an API based on its maturity state and retrieve the API for implementation. Also, you can use this to update the maturity state of an API after implementation. Typically, the value of this parameter would be the consecutive state defined in the apiMaturityStatePossibleValues extended setting configuration.
    For example,
    If any of the following states are configured in the apiMaturityStatePossibleValues setting : Design, Implementation, Testing, Production; and current state of an API is Implementation, then you must specify Testing as the parameter value because that would be next stage as per the configuration.