API Implementation
No subtopics in thissection
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:
Enable API mocking
Enforce policies
Ensure proper caching, filtering and error handling mechanisms
Enforce policies
Apply rate limiting
Enable API testing and debugging
Define monitoring and debugging mechanisms
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
Enabling API MockingModifying API Mocking DetailsCustom ReplacerUsing 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.
- 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:
If any of the conditions for the invoked operation satisfies, API Gateway returns the associated mocked response.
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.
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.
Enabling API Mocking
You can enable or disable API mocking through the API details page.
To enable API mocking
Click APIs in the title navigation bar.
Select the required API from the list of available APIs.
The API details page for the selected API appears.Click 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
Click APIs in the title navigation bar.
A list of all registered APIs appears.Click the required API. The API details page appears.
Click Edit.
Click API mocking.
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. Select the operation that you want to modify from the Mocked responses section.
Click Add Response if you want to add a response and select the status code from the drop-down.
Click .
This adds the status code created to the existing status code list.Select the status code you want to modify.
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 .
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.
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.
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:
${request.header.<headerKey>}
: To replace the value of theheaderKey
from the request headers.${request.query.<queryKey>}
: To replace the value of thequeryKey
from the query parameters in the request URL.${request.body.<JsonPath|XPath>}
: To replace the value of the<JsonPath|XPath>
from the request body.
Consumer Applications
Creating an ApplicationViewing List of Applications and SubscriptionsRegenerating API Access KeyModifying Application DetailsRegistering an API with Consumer Applications from API Details PageSuspending an ApplicationActivating a Suspending ApplicationAn 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:
Control access to an API at run time (that is, allow only authorized applications to invoke an API).
Monitor an API for violations of a Service-Level Agreement (SLA) for a specified application.
Indicate the application to which a logged transaction event belongs.
An application has the following attributes for specifying the identifiers:
IP address, which specifies one or more IP addresses that identify requests from a particular application. Example:
192.168.0.10
This attribute is queried when the Identify and Authorize Application policy is configured to identify applications using IP address.Claims set, which specifies one or more claims that identify requests from a particular application. The claims are a set of name-value pairs that provide sufficient information about the application. Example:
sub = Administrator
.
This attribute is queried when the Identify and Authorize Application policy is configured to identify applications using a JWT token or an OpenID token.Client certificate, which specifies the X.509 certificates that identify requests from a particular application.
This attribute is queried when the Identify and Authorize Application policy is configured to identify the applications by a client certificate.Identification token, which specifies the host names, user names or other distinguishing strings that identify requests from a particular application.
This attribute is queried when the Identify and Authorize Application policy is configured to identify applications by host name, token, HTTP user name, and WSS user name.
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:
API developers request the API Gateway administrators to create an application for access as per the required identification criteria.
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).
API Developer, upon finding a suitable API, sends a request to API Gateway for consumption by providing the application details.
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.
NoteThe approval process, if any, is handled by the requesting application and not handled by API Gateway.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
Click Applications in the title navigation bar.
Click Create application.
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.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.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 +AddClaims 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.
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.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.Type the required Requestor comment.
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.Specify the origin from which the responses originating are allowed during response processing for the application.
Click +Add to add the origin.
You can add multiple origins using .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.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.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.
Click Add.
The strategy is configured and listed in the Strategies table.NoteAPI 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.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
Click Applications in the title navigation bar.
A list of all registered applications and subscriptions appear.- denotes application.
- denotes subscription.
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.
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.NoteYou 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
Click Applications in the title navigation bar.
A list of all registered applications is displayed.Select an application.
The application details page displays the basic information, identifiers, access tokens, API key, APIs registered and strategies configured for that application.Click .
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
Click Applications in the title navigation bar.
A list of registered applications is displayed.Select an application.
Click Edit in the application details page.
Modify the required fields in the Basic information section.
Note: You cannot modify ownership details of the applications you create through Developer Portal.Click Identifiers.
Modify the required fields in the Identifiers section.
Click APIs.
Add or delete the APIs that are registered.
Modify the strategies or create a new strategy.
Modify the required values.
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
Click APIs in the title navigation bar.
A list of APIs is displayed.Select an API.
Click Edit in the API details page.
Click Application tab in the API details page.
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.Select the required applications and click +.
You can add more applications in a similar way.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
Click Applications in the title navigation bar.
A list of all the available applications are displayed.Click the toggle button (Active state), in the action column for the respective application, to suspend the application.
Alternatively, you can click Suspend in the application details page.Click Yes in the confirmation dialog box.
The application is suspended. The toggle button in the Applications page changes to (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
Click Applications in the title navigation bar.
A list of all the available applications are displayed.Click the toggle button (suspended state), in the action column for the respective application, to activate the application.
Alternatively, you can click Activate in the application details page.Click Yes in the confirmation dialog box.
The application resumes. The toggle button in the Applications page changes to (active state) and the option in the application details page changes to Suspend.
Policies
TransportEnable BulkheadEnabling bulkhead for APIs at the API-levelBulkhead feature considerationsEnable HTTP/HTTPSSet Media TypeIdentify and AccessInbound Auth - MessageIdentify & AuthorizeOAuth, JWT, and OpenID ConfigurationOAuth Authentication Use Case and WorkflowJWT Authentication Use Case and WorkflowOpenID Authentication Use Case and WorkflowSecure API using OAuth2 with refresh token workflowConfiguring OAuth2 Authentication with Refresh TokenRefresh Token Process FlowHow to get the access token with resource owner permission?How to get the access token without resource owner permission using refresh token in the subsequent attempts?Securing Access Token Calls with PKCEHow do I enforce PKCE globally?How do I enforce PKCE at application level?How do I secure the access token with Authorization Code (With PKCE) grant type using postman?How do I secure the access token by directly calling API Gateway’s REST APIs?How do I enforce PKCE selectively for each access token call?How do I generate code verifier and code challenge?Inbound Auth - MessageAuthorize UserRequest ProcessingValidate API SpecificationRequest TransformationData MaskingRoutingStraight Through RoutingCustom HTTP HeaderOutbound Auth - TransportContent-based RoutingConditional RoutingDynamic RoutingLoad Balancer RoutingOutbound Auth - MessageTraffic MonitoringLog InvocationTraffic OptimizationTraffic Optimization Policy Enforcement ScenariosService Result CacheMonitor PerformanceMonitor SLAResponse ProcessingValidate API SpecificationResponse TransformationData MaskingCORSError HandlingConditional Error ProcessingData MaskingPolicy Validation and DependenciesVariable FrameworkRequest VariablesResponse variablesSystem Context VariablesEnhancements to Variable Framework SupportCustom Policy ExtensionHow Do I Invoke a Service through HTTP/HTTPS using Custom Extension?How Do I Invoke an AWS Lambda Function using Custom Extension?How Do I Define a Custom Variable?Custom Extension PropertiesRequest Processing SectionResponse Processing sectionCustom Extension Metadata sectionData Objects and Variables Available in API GatewayRequest and Response Transformation PoliciesHow do I transform a request using Request Transformation Policy?Request Transformation Policy PropertiesHow do I transform a request and its response using Transformation Policy?Response Transformation Policy PropertiesSystem Context VariablesThe API for Context Variablespub.apigateway.ctxvar:getContextVariablepub.apigateway.ctxvar:setContextVariablepub.apigateway.ctxvar:declareContextVariablepub.apigateway.ctxvar:removeContextVariableSample Flow Service: Getting a Context Variable ValueStep 1. Declaring customNameStep 2. Setting customName to mx:COMP_TESTStep 3. Displaying the value of customNameStep 4. Calling meditor.ctxvar:getContextVariableStep 5. Sample service using the context variableSample Flow Service: Setting a Context Variable ValueStep 1. Declaring customNameStep 2. Setting customName to mx:COMP_TESTStep 3. Displaying the value of customNameStep 4. Calling meditor.ctxvar:getContextVariableStep 5. Sample service using the context variableAssigning a Policy to an APIViewing API Policy DetailsModifying API Policy DetailsAPI 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:
Verify that the requests submitted to an API come from applications that are authenticated and authorized using the specified set of identifiers in the HTTP header to access and use the particular API.
Validate digital signatures in the security header of request and response messages.
Monitor a user-specified set of run-time performance conditions and limit the number of invocations during a specified time interval for a particular API and for applications, and send alerts to a specified destination when these performance conditions are violated.
Log the request and response messages, and the run-time performance measurements for APIs and applications.
You can enforce policies in an API in the following ways:
Global policy enforcement. This enforcement applies globally to all APIs defined in API Gateway. For example, the threat protection policies can be enforced for all APIs to protect against malicious attacks. For more information about threat protection policies, see Threat Protection Policies.
API-level policy enforcement. This enforcement applies to all resources and its nested methods of a REST API, or all operations of a SOAP API. These policies are further categorized into stages depending on their usage such as:
For example, the Identify and access category of policies can be enforced on an API to specify the kind of identifiers that are used to identify the application and authorize it against all applications registered in API Gateway.
Scope-level policy enforcement
- Resource-level policy enforcement. Applicable only for REST APIs. This enforcement applies to one or more resources and its nested methods in the REST API.
- Method-level policy enforcement. Applicable only for REST APIs. This enforcement applies to one or more methods nested within a resource in the REST API.
-OR- - Operation-level policy enforcement. Applicable only for SOAP APIs. This enforcement applies to one or more operations in the SOAP API.
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:
Global Policy Enforcement
Method-level Policy Enforcement or Operation-level Policy Enforcement
Resource-level Policy Enforcement
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:
Any policy (for example, Log Invocation) that can appear in an API multiple times is allowed to appear multiple times.
For policies (for example, Require HTTP / HTTPS) that can appear only once in an API, API Gateway issues an error message.
For policies (for example, Monitor SLA) that are dependent and use another policy in conjunction (for example, Identify and Authorize Application) in an API, API Gateway prompts you with a warning message to include the dependent policy.
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 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
Enable HTTP/HTTPS
Set Media Type
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
Bulkhead limit for an API at the API level. Specifies the maximum concurrent request limit for an API, exceeding which the requests are rejected. This number does not include the callbacks that an API receives. So, you can separately specify the maximum concurrent callbacks that an API can handle. The
503 Service unavailable
error code is sent to the client service when the requests are rejected. You can configure the required error code and status phrase using the extended settings. You can customize the required status code and message using the extended settings pg.bulkhead.statusCode and pg.bulkhead.statusMessage respectively.Bulkhead limit for all APIs (Global policy). Specifies the maximum concurrent request limit for all APIs. Similar to the API level configuration, you can provide the maximum concurrent callbacks and your choice to retry the rejected requests.
When you have configured global-level bulkhead limit for APIs, and if you configure a different bulkhead limit at an API-level, then the limit configured at the global level takes precedence. To override this, you must exclude the required APIs from the global-policy using filters. You can apply the required API filters when creating or editing the bulkhead global policy. For information about creating global policies and applying API filters, see Creating a Global Policy.
Add Retry-After response header. Specifies whether the Retry-After header must be included in the response sent to the client when requests are rejected. If you select to add, you must also specify the duration (in seconds) that the system must wait before sending the consecutive requests. You can configure this setting to keep the client informed on the waiting duration before processing the consecutive requests.
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
Click APIs in the title navigation bar.
Select the required API.
Click the Policies tab.
From the Policy catalog section, expand Transport, and select Enable bulkhead.
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.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:
|
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 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:
Inbound Auth - Message
Identify & Authorize
Custom Extension
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.
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:
In the SOAP Header section, provide the following information:
You can add more SOAP headers by clicking . |
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:
You can add more namespace prefixes and URIs by clicking . |
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:
You can add more namespace prefixes and URIs by clicking . |
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:
For the SOAP Header section, provide the following information:
You can add more namespace prefixes and URIs by clicking . |
Match Criteria | Select one of the following options:
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 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:
- Registered applications. Identifies the application and validates the identified application against the registered applications. On successful validation, API Gateway allows access to the API. The applications that are associated with the API are called as registered applications.
- Global applications. Identifies the application and validates the identified application against the global applications. On successful validation, API Gateway allows access to the API. All the active applications that are available in API Gateway are called as global applications.
- Global applications and DefaultApplication. Verifies the identity of the application against the global applications and on identification failure, the API Gateway allows access to the API as default application.
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:
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 as |
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:
When this option is selected, you can use the API key as: |
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:
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:
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:
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:
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:
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:
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:
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:
|
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:
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:
|
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:
In the Payload identifier section, click Add payload identifier, provide the following information, and click Add.
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:
|
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
Resource Owner (or the End User). This is the holder of the protected resources that the client application accesses. The resource owner is typically a person (usually the end user), but could also be an application.
Client Application (or the Client). This is the application that is requesting access to protected resources on behalf of the end user.
Resource Server (or API Gateway). This is the server that stores the protected resources the application is trying to access. API Gateway acts as a resource server.
Authorization Server. This is the server that acts as an interface between the client application and end user, authenticates the end user, and issues access tokens after proper authorization. API Gateway can be configured to act as an OAuth 2.0 authorization server. You can configure API Gateway for use with a third-party OAuth 2.0 authorization server, such as PingFederate.
Authorization Grant Types
Authorization Code. This is the grant type used to obtain access tokens (and optionally refresh tokens) and is optimized for confidential clients.
For public clients, the Authorization Code grant type can be further secured by PKCE mechanism. For details, see Securing Access Token Calls with PKCE.NoteAPI Gateway supports the confidential client authentication using Authorization headers. The confidential clients have to authenticate using their credentials, the client id and client secret combination. Few points to consider using the Authorization Code grant type:
- If the property
watt.server.oauth.token.endpoint.auth=session
(the default value) and the confidential client already has a session when it comes to the token endpoint, the access to the endpoint is granted even if there are no credentials in the header. - If the property
watt.server.oauth.token.endpoint.auth=credentials
or if the client does not already have a session, the confidential client must provide the client_secret in the Authorization header. - API Gateway does not support the client secret in the body of the request for the Authorization code grant.
- If the property
Implicit. This is the grant type used to obtain access tokens and is optimized for public clients. It does not support the issuance of refresh tokens.
Client Credentials. This is the grant type used to obtain access tokens for client-only authentication.
Resource Owner Password Credentials. This is the grant type used to obtain access tokens when the resource owner has a trust relationship with the client, and clients are capable of obtaining the resource owner’s credentials.
Clients
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.
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.
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:
To introspect the token, you should have a JWKS URI or you should create a client account that API Gateway uses to call the authorization server’s introspection endpoint.
Make a note of the client_id and client_secret values. You provide this information as part of defining the external authorization server alias for the API Gateway resource server.
Make a note of the URL for the introspection endpoint. You provide this information as part of defining the external authorization server alias in the API Gateway resource server.
Validation of JWT token of the external authorization server happens in the following ways:Local Introspection Remote Introspection Validation of the JWT token happens within the gateway in the following methods:
Using JWKS URI. The external authorization server’s signature is verified by using the public certificate in the JWKS URI.
API Gateway’s cache has a key as kid claim and its value is the certificate corresponding to the kid claim. The cache is populated on every restart of API Gateway by invoking the JWKS URI.
In the runtime, while validating the token using the local introspection, the kid value from the incoming JWT is fetched and the corresponding certificate is retrieved from the cache and the signature validation happens.
Using RSA. The external authorization server’s signature in the JWT is verified by the truststore defined in the local introspection configuration.
Using HMAC. If the authorization server uses HMAC algorithm, that means the signature validation of the JWT is performed using a shared key between the authorization server and API Gateway. You must specify the HMAC shared secret when creating the strategy of the application. The HMAC shared secret in the application is used to validate the authorization server’s signature present in JWT.Validation of the JWT token happens with the authorization server. Therefore, token caching is not possible in remote introspection.
It has an introspection endpoint, which is used to validate the token. In addition, the client id and client secret are used to protect the endpoint, so that anonymous users cannot access the resource. To invoke an endpoint, you require a user; Gateway user is the one you can use to invoke the endpoint.Create the required scopes.
Configure an alias to the authorization server.
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:
Okta
PingFederate
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.
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.
Map the scopes.
For a complete procedure on mapping scopes, see Mapping OAuth or OpenID Scopes.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.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.Activate the API.
User on invoking the API uses the OAuth identification method to access the protected resource.Get access token through the following URLS:
invoke/pub.apigateway.oauth2/authorize
invoke/pub.apigateway.oauth2/getAccessToken
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.
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.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.Map the scopes.
For a complete procedure on mapping scopes, see Mapping OAuth or OpenID Scopes.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.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.Activate API.
User on invoking the API uses the OAuth identification method to access the protected resource.Get the access token from the authorization server.
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:
The OAuth authorization workflow is as follows:
The end user logs in, the client application sends the authentication request to the authorization server to obtain an access token.
Authorization server validates the request and generates an access token for the client.
Client uses this access token to send HTTP requests to API Gateway.
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.
NoteWhen 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.
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.
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.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.
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.Activate the API.
User on invoking the API uses the JWT identification method to access the protected resource.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.
Configure an external authorization server.
For a complete procedure on configuring an external authorization server, see Adding an External Authorization Server.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.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.Activate the API.
User on invoking the API uses the JWT identification method to access the protected resource.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:
The JWT authorization workflow is as follows:
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.
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.Client sends the generated JSON token in the HTTP Authorization request header as a Bearer token to access the protected API in API Gateway.
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.):
Use just the access tokens (that is OAuth token) to invoke the protected resources.
Use the ID token (that gives information about the user) to invoke the protected resources in one of the following ways:
Present the ID token to exchange it for an access token and use the access token to access the protected resources.
Use the ID token directly to access the protected resources.
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
Method: POST
URL:
http://hostname/gateway/security/exchangeIDToken
Payload:
{ "gatewayScopes": ["OktaTenant1:inventory"], "idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjQwYzZiMDliNDQ5NjczNDUzYzNkYTY" "expiry": 3000 }
For details on scopes, see Mapping OAuth or OpenID Scopes.
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.
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.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.Map the scopes.
For a complete procedure on mapping scopes, see Mapping OAuth or OpenID Scopes.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.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.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.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.
OpenID authorization workflow using the access token provided by the Open ID Connect Provider
The client makes an OpenID call to the OpenID connect Provider.
The OpenID Connect Provider provides an access token to the client.
The client application presents the access token received from the OpenID Connect Provider to send HTTP requests to API Gateway.
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
The client makes an OpenID call to the OpenID Connect Provider.
The OpenID Connect Provider provides an ID token to the client.
The client application presents the ID token received from the OpenID Connect Provider to API Gateway.
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.
The client then uses this access token to send HTTP requests to API Gateway.
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.
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
Create an API. For details about creating an API, see Creating an Rest API.
Enable the OAuth2 token identification type in the Identify & Authorize policy. For details about Identify & Authorize policy, see Identify & Authorize.
Create OAuth scope in the local authorization server.
Map the OAuth scope to the API scope. For details about mapping OAuth scope, see Mapping OAuth or OpenID Scopes.
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.
NoteTo 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.
NoteMake 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?
How to get the access token without resource owner permission using refresh token in the subsequent attempts?
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)
Get authorization code.
a. Click the http(s)://hostname/invoke/pub.apigateway.oauth2/authorize?response_type=code&redirect_uri=<redirectURI>&client_id=<Client ID>.
NoteMake 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.
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" }
NoteYou 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 }
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.
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" }
NoteMake 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 }
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.
- 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:
- Code Verifier. The code verifier should be a high-entropy cryptographic random string with a minimum of 43 characters and a maximum of 128 characters.
- Code Challenge. The code challenge is created by SHA256 hashing the code verifier and then applying base64 URL encoding of the resulting hash. If the client cannot do the hashing and encoding transformation, it can use the code challenge method as plain where the code challenge is same as code verifier
- Code Challenge Method. This is an optional parameter. If the client uses SHA256 hashing, the code challenge method value must be S256. If no hashing is done, then the code challenge method value must be plain. When code challenge method is plain , the code challenge value is the same as the code verifier. If the code challenge method value is not passed in the client request, then plain would be considered as default value.
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:
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.
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.
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.
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:
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
Expand the menu icon, in the title bar, and select Administration.
Select Security > JWT/OAuth/OpenID.
The Authorization servers section displays a list of available internal and external authorization servers.In the Internal authorization servers section, click local .
Expand the OAuth configurationsection, select the Enforce PKCE checkbox.
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
Create OAuth scope in the local authorization server.
Create a new application or update an existing application with OAuth2 authentication strategy.
For details about creating an application, see Creating an Application.
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:
- 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.
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?NoteThe application level PKCE enforcement takes precedence over the global level PKCE enforcement.- Select the Authentication schemes as
Click Add to save the strategy.
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
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.
NoteYou 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:
generated Code Challenge and Code Verifier. For details about how to generate code challenge and code verifier, see How do I generate code verifier and code challenge?
enforced PKCE at global level at global level or application level.
To secure the access token
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
NoteMake 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.
NoteIf 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.
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" }
NoteYou 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
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?
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.
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:
In the SOAP Header section, provide the following information:
You can add more SOAP headers by clicking . |
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:
You can add more namespace prefixes and URIs by clicking . |
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:
You can add more namespace prefixes and URIs by clicking . |
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:
For the SOAP Header section, provide the following information:
You can add more namespace prefixes and URIs by clicking . |
Match Criteria | Select one of the following options:
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 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.
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 to add. You can add more users. Click 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 to add. You can add more groups. Click 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 to add. You can add one or more teams. Click 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
Request Transformation
Data Masking
Custom Extension
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.
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 schema is available as part of the API definition. The schema for SOAP API are imported through WSDL and for REST APIs it can be through swagger, RAML or can be uploaded by the user.
The query parameters, path parameters and content- types are available as part of the API definition.
The HTTP Headers are specified in the Validate API Specification policy page.
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:
Schema:
The incoming requests are validated against the schema provided in the API definition. The schema defines the elements and attributes and specifies the data types of these elements to ensure that only appropriate data is allowed through to the API.
For a REST API, the schema can be added inline or uploaded in the Technical Information section on the API Details page. The validation depends on the Content-type header in the request or Accept header in the response and the corresponding schema validation would be executed.
The schema type for validation is selected based on:
- The Content-Type header when the policy is added in the Request processing stage.
- The Accept header when the policy is added in the Response processing stage.
If the header or payload is missing the schema validation is skipped.
The table lists the default Content type/Accept header and schema validation type mapping.
Content-type/Accept Schema validation type application/json
application/json/badgerfishJSON schema application/xml
text/xml
text/htmlXML 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.
NoteIf schema mapping is not found for a content-type of the request in the API, the behavior is as follows:- If schema mapping is not available in a REST API or SOAP-to-REST transformed API, the validation is skipped.
- If application/json is mapped to XML schema in the API definition, then the JSON content in the request is validated against XML schema to provide a backward compatibility support for APIs migrated from the 10.1 version.
- If only XML schema mappings exist for any of the content-types, the payload is converted into XML and validated against all the XML schemas. If the payload is valid against one of the schemas, the validation is successful.
- If the payload is not XML convertible, the validation is not performed and the request is allowed to reach the native API.
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. The incoming requests are validated against the query parameters specified in the API definition.
Path Parameters:
This is applicable only for a REST API. The incoming requests are validated against the path parameters specified in the API definition.
Content-types:
This is not applicable to a GraphQL API. The incoming requests are validated against the content-types specified in the API definition.
NoteWhen Content-type validation is selected for a SOAP API, the validation fails in case of SOAP to REST scenarios and displays an error with 500 status code instead of 400 as displayed in the other scenarios.When we have Content type validation selected for SOAP API, when SOAP TO REST scenarios, this validation does not happen, that is, an error displays with 500 status code and not 400 as the other scenarios.
HTTP Headers:
This is not applicable to a GraphQL API. The incoming requests are validated against the HTTP Headers specified in this policy to conform to the HTTP headers expected by the API.
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.
Select the required feature names from the list: 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. 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:
Available values are: You can add more HTTP headers by clicking |
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:
Click Add Condition and provide the following information and click .
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:
You can add multiple variables and corresponding values by clicking . 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:
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:
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.
|
Transformation Metadata. Specifies the metadata for transformation of the incoming requests. For example, the namespaces configured in this section can be used when you provide the syntax for XPath {request.payload.xpath[//ns:emp/ns:empName]} | |
Namespace | Specifies the namespace information to be configured for transformation.
Provide the following information:
|
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.
- 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 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 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:
|
|
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:
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:
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 . |
|
Apply for transaction Logging | Select this option to apply masking criteria for transactional logs.
Note: For REST enabled SOAP services
|
|
Apply for payload | Select this option to apply masking criteria for request payload in the following scenarios:
|
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:
Straight Through Routing
Custom HTTP Header
Outbound Auth - Transport
Content-based Routing
Conditional Routing
Dynamic Routing
Load Balancer Routing
Outbound Auth - Message
Custom Extension
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.
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://{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 {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:
|
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:
|
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:
|
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.
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 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 .
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.
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:
|
Authenticate using | Select one of the following modes to authenticate the client:
|
Basic | Uses the HTTP authentication details to authenticate the client. API Gateway supports the following modes of HTTP authentication:
|
Kerberos | Uses the Kerberos credentials to authenticate the client. API Gateway supports the following modes of Kerberos authentication:
Provide the following credentials |
NTLM | Uses the NTLM credentials to authenticate the client. API Gateway supports the following modes of NTLM authentication:
Provide the following credentials |
OAuth2 | Uses the OAuth2 token to authenticate the client. API Gateway supports the following modes of NTLM authentication:
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.
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://{request.headers.nativeport}/${sys:resource-path}, where the ${myAliasHost} variable syntax is used to define the simple alias and the ${request.headers.nativeport} variable syntax is used to define the native port based on the request. For details about the variables available in API Gateway, see Variables available in API Gateway. Note:If you use endpoint alias, make sure the endpoint alias is created before you define it in the policy. For example, if you define {alias} 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:
|
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:
|
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:
|
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.
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 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.
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://{request.headers.nativeport}/${sys:resource-path}, where the ${myAliasHost} variable syntax is used to define the simple alias and the ${request.headers.nativeport} variable syntax is used to define the native port based on the request. For details about the variables available in API Gateway, see Variables available in API Gateway. Note:If you use endpoint alias, make sure the endpoint alias is created before you define it in the policy. For example, if you define {alias} 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:
|
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:
|
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:
|
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:
|
Service Registry Configuration | |
Service Discovery Endpoint Parameter | Values required for constructing the discovery service URI.
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 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.
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://{request.headers.nativeport}/${sys:resource-path}, where the ${myAliasHost} variable syntax is used to define the simple alias and the ${request.headers.nativeport} variable syntax is used to define the native port based on the request. For details about the variables available in API Gateway, see Variables available in API Gateway. Note:If you use endpoint alias, make sure the endpoint alias is created before you define it in the policy. For example, if you define {alias} 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:
|
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:
|
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:
|
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.
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 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:
|
Add Condition | Specify the context variables for processing client requests.
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://{request.headers.nativeport}/${sys:resource-path}, where the ${myAliasHost} variable syntax is used to define the simple alias and the ${request.headers.nativeport} variable syntax is used to define the native port based on the request. For details about the variables available in API Gateway, see Variables available in API Gateway. Note:If you use endpoint alias, make sure the endpoint alias is created before you define it in the policy. For example, if you define {alias} 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:
|
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:
|
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:
|
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:
|
Service Registry Configuration | |
Service Discovery Endpoint Parameter | Values required for constructing the discovery service URI.
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 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.
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://{request.headers.nativeport}/${sys:resource-path}, where the ${myAliasHost} variable syntax is used to define the simple alias and the ${request.headers.nativeport} variable syntax is used to define the native port based on the request. For details about the variables available in API Gateway, see Variables available in API Gateway. Note:If you use endpoint alias, make sure the endpoint alias is created before you define it in the policy. For example, if you define {alias} 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:
|
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:
|
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:
|
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.
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 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:
|
Route To | Specifies the endpoint URI of native services in a pool to which the requests are routed.
Provide the following information:
|
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:
|
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://{request.headers.nativeport}/${sys:resource-path}, where the ${myAliasHost} variable syntax is used to define the simple alias and the ${request.headers.nativeport} variable syntax is used to define the native port based on the request. For details about the variables available in API Gateway, see Variables available in API Gateway. Note:If you use endpoint alias, make sure the endpoint alias is created before you define it in the policy. For example, if you define {alias} 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:
|
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:
|
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:
|
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.
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 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.
- 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:
|
Authenticate using | Select one of the following modes to authenticate the client:
|
WSS username | Uses the WSS credentials to authenticate the client. Provide the following credentials:
|
Kerberos | Uses the Kerberos credentials to authenticate the client. Provide the following information:
|
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:
|
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
Traffic Optimization
Service Result Cache
Monitor Performance
Monitor SLA
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:
|
Destination | Specifies the destination where to log the payload. Select the required options:
|
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:
- Policy violation event. Indicates the violations that occur for an API. If there are 100 violations, then 100 policy violation events are generated.
- Monitor event. Controlled by the alert frequency configuration specified in the policy.
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:
|
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:
|
Alert Frequency | Specifies the frequency at which the alerts are issued.
Specify one of the options:
|
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:
|
Consumer Applications | Specifies the consumer applications for which the policy is applied. Do one of the following:
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 |
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?
- Allow 1000 invocation per minute for each registered consumer application.
- Allow 500 invocation for 15 minutes for all non-registered consumer applications.
Possible solution:
Create two Traffic Optimization policies with the following specifications
- Policy 1
- value.
1000.
- Alert Interval.
1.
- Alert Frequency.
minute.
- Consumer Applications.
Each registered consumer.
- value.
- Policy 2
- value.
500
. - Alert Interval.
15.
- Alert Frequency.
minute.
- Consumer Applications.
All non-registered consumers.
- value.
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.
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 .
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 . |
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.
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 .
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:
- If the incoming request R1 matches criteria C1, then the result is cached. API Gateway responds to any further incoming request R1 that matches criteria C1 from the cache.
- If the incoming request R1 matches criteria C1 and C2, then the result is cached as a new request.
- If you configure multiple cache criteria, and if one or more cache criteria match, then the result is cached. The criteria are matched with the cached results while caching the request, and it follows the AND condition among the matched criteria.
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:
|
||||||||||||||||||||||||||||||||||||||||
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:
|
||||||||||||||||||||||||||||||||||||||||
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:
|
||||||||||||||||||||||||||||||||||||||||
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:
|
||||||||||||||||||||||||||||||||||||||||
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:
|
||||||||||||||||||||||||||||||||||||||||
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:
|
||||||||||||||||||||||||||||||||||||||||
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:
|
||||||||||||||||||||||||||||||||||||||||
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:
|
||||||||||||||||||||||||||||||||||||||||
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 to add it. You can add multiple applications or delete an added application by clicking . |
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
Response Transformation
CORS
Data Masking
Custom Extension
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.
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 schema is available as part of the API definition. The schema for SOAP API are imported through WSDL and for REST APIs it can be through swagger, RAML or can be uploaded by the user.
The content- types are available as part of the API definition. FOR SOAP APIs these are imported through WSDL and for REST APIs it can be through swagger, RAML or can be uploaded by the user.
The HTTP Headers are specified in the Validate API Specification policy page
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:
Schema:
The responses from the native API are validated against the schema provided in the API definition. The schema defines the elements and attributes and specifies the data types of these elements to ensure that only appropriate data is allowed through to the API.
For a REST API, the schema can be added inline or uploaded in the Technical Information section on the API Details page. The validation depends on the Content-type header in the request or Accept header in the response and the corresponding schema validation would be executed.
The schema type for validation is selected based on:
- The Content-Type header when the policy is added in the Request processing stage.
- The Accept header when the policy is added in the Response processing stage.
If the header or payload is missing the schema validation is skipped.
The table lists the default Content type/Accept header and schema validation type mapping.
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.
Content-types:
The responses from the native API are validated against the content-types specified in the API definition.HTTP Headers:
The responses from the native API are validated against the HTTP Headers specified in this policy to conform to the HTTP headers expected by the API.
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:
Select the required feature names from the list: 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. |
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:
Available values are: You can add more HTTP headers by clicking |
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:
Click Add Condition and provide the following information and click .
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:
You can add multiple variables and corresponding values by clicking . 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:
|
Payload Transformation | Specifies the payload transformation to be configured for the responses received from the native API.
Provide the following information:
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.
|
Transformation Metadata. Specifies the metadata for transformation of the responses received from the native API. For example, the namespaces configured in this section can be used when you provide the syntax for XPath {response.payload.xpath[//ns:emp/ns:empName]} | |
Namespace | Specifies the namespace information to be configured for transformation.
Provide the following information:
|
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.
- 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 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 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:
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. |
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:
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:
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 . |
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:
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.
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:
Origin
Access-Control-Request-Method
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:
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:
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:
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:
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. |
- 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
Data Masking
Custom Extension
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.
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:
Click Add Condition and provide the following information and click .
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:
You can add multiple entries for feature name and value by clicking . 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:
You can add multiple variables and corresponding values by clicking . 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:
For example if you want to transform status code as 403, provide 403 in the Code field. 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:
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.
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. |
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:
You can add multiple entries for feature names and values by clicking . Note: API Gateway supports XSLT 1.0 and XSLT 2.0. |
Transformation Metadata. Specifies the metadata for transformation of the error responses received from the native API. For example, the namespaces configured in this section can be used when you provide the syntax for XPath {response.payload.xpath[//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:
For example, specify the namespace URI as You can add multiple namespace prefixes and URIs by clicking . You can add multiple namespace prefixes and URIs by clicking **+Add**. |
Data Masking
Data masking is a technique whereby sensitive data is obscured in some way to render it safe and to protect the actual data while having a functional substitute for occasions when the real data is not required.
This policy is used to mask sensitive data in the custom error messages being processed and sent to the application. Fields can be masked or filtered in the error messages. You can configure the masking criteria as required for the XPath, JPath, and Regex expressions. This policy can also be applied at the API scope level.
The table lists the masking criteria properties that you can configure to mask the data in the request messages received:
Parameter | Description |
---|---|
Consumer Applications | Specifies the applications for which the masking criterion has to be applied.
Start typing the application name, select the application from the type-ahead search results displayed, and click to add one or more applications. You can use the delete 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:
|
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:
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:
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 . |
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 dependencies (that is, whether a policy must be used in conjunction with another particular policy).
Conflicting or incompatible policies.
Whether a policy can be included multiple times in a single API. If a policy cannot be included multiple times in a single API, API Gateway selects one (depending on the precedence of the policy at the enforcement level) for the effective policy and processes at run-time.
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.
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:
|
paramType |
Defines the specific parameter of the request or response. Possible values are:
|
queryType |
Defines the query that can be applied over string elements like payload. Possible values are:
|
The following variable types are available in the request or response stages:
${paramStage.paramType}
You can use this syntax to access the following string variables:
path
,statusCode
,statusMessage
,httpMethod
.Examples:
${request.path}
,${response.statusCode}
${paramStage.paramType.paramName}
You can use this syntax to access map types, such as query, headers, and path.
Example:
${request.query.var1}
,${response.header.Content-Type}
,${request.path.name}
.${paramStage.paramType.queryType[queryValue]}
You can use this syntax to access the payload. Examples:
${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, text/xml, or text/html.${response.payload.jsonPath[$.cardDetails.number]}
Where
$.cardDetails.number
is the jsonPath to be applied on payload if contentType is application/json or application/json/badgerfish.${request.payload.regex[[0-9]+]}
Where
[0-9]+
is the regular expression to be applied on the payload if contentType is text/plain.${request.isSoapToRest}
or${response.isSoapToRest}
This variable returns True if the current invoke is REST invoke for a SOAP API. Else it returns False.
xpath
and jsonPath
are applicable only to payload, regEx
can be used with both payload
and path
.${paramStage[stepName].paramType.paramName]}
You can use this syntax to access the header or payload in the request or response stage.
Example:
Variable:
${response.headers.id}
Value:
${response[customExtension].payload.jsonPath[$.id]}
This transformation adds a header to the response with the name id, and its value is derived from the JSON payload that is sent from the external callout as per the JSON path.
The following sections summarize the variables that are available in API Gateway as part of variable framework template in addition to the existing predefined system context and custom context variables:
Request Variables
Variables that allow you to extract and reuse values in the request processing stage.
Variable Syntax | Description |
---|---|
${request.headers.NAME} Example: ${request.headers.Content-Type} |
Gets the value of the header name in the request. |
${request.query.NAME} Example: ${request.query.var1} |
Gets the value of the query name in the request. |
${request.path} |
Gets the value of the path in the request. |
${request.path.regex[EXPR]} Example: ${request.path.regex[0]} |
Gets the value of the path in the request. |
${request.httpMethod} |
Gets the method in the request. |
${request.payload.xpath[EXPR]} Example: ${request.payload.xpath[//ns:emp/ns:empName]} , where //ns:emp/ns:empName is the xpath to be applied on the payload if contentType is application/xml |
Gets the value after applying a xpath expression on the request path. Note: The namespace URI for the prefixes you have configured in the xpath expression are resolved using namespaces configured in the metadata section in the policy or using the namespaces configured through XpathNamespaces custom variable in the custom extension policy . |
${request.payload.jsonPath[EXPR]} Example: ${request.payload.jsonPath[$.cardDetails.number]} where $.cardDetails.number is the jsonPath to be applied on the payload if contentType is application/json |
Gets the value after applying a json expression on the request path. |
${request.payload.regex[EXPR]} Example: ${request.payload.regex[[0-9]+]} where [0-9]+ is the regex to be applied on the payload if contentType is text/plain |
Gets the value after applying a regular expression on the request path. |
${request.authorization.clientId} |
Gets the value of the client ID identified from the authorization header by the configured IAM policy. This value is available only if the relevant IAM policy is configured. |
${request.authorization.issuer} |
Gets the value of the issuer identified from the authorization header by the configured IAM policy. This value is available only if the relevant IAM policy is configured. |
${request.authorization.userName} |
Gets the value of the username identified from the authorization header by the configured IAM policy. This value is available only if the relevant IAM policy is configured. |
${request.authorization.authHeader} |
Gets the value of the authorization header by the configured IAM policy. This value is available only if the relevant IAM policy is configured. |
${request.authorization.apiKey} |
Gets the value of the API key from the authorization header by the configured IAM policy. This value is available only if the relevant IAM policy is configured. |
${request.authorization.incomingToken} |
Gets the value of the incoming token from the authorization header by the configured IAM policy. This value is available only if the relevant IAM policy is configured. |
${request.authorization.audience} |
Gets the value of the audience from the authorization header by the configured IAM policy. This value is available only if the relevant IAM policy is configured. |
${request.authorization.claims.CLAIM_NAME} Example: ${request.authorization.claims.emp.company} |
Gets the value for the claim name from the claims identified from the Authorization header by the configured IAM policy. This value is available only if the relevant IAM policy is configured |
${request.correlationID} |
Gets the correlation ID for this request. |
${request.application.id} |
Gets the ID of the application identified for this request. |
${request.application.name} |
Gets the name of the application identified for this request. |
${request.application.version} |
Gets the version ID of the application identified for this request. |
${request.application.claims.CLAIM_NAME} Example: ${ request.application.claims.sample } |
Gets the value of the claim name for the claims identifier configured in the application identified for this request. |
${request.application.partnerId} |
Gets the partner ID of the application identified for this request. |
${request.application.description} |
Gets the description of the application identified for this request. |
${request.application.hostname[NUMBER]} Example: ${ request.application.hostname[0]} |
Gets the value of the hostname identifier in the specified index for the application identified for this request. |
${request.application.payloadIdentifier[NUMBER]}<br> Example: ${request.application.payloadIdentifier[1]}` |
Gets the value of the payload identifier in the specified index for the application identified for this request. |
${request.application.team[NUMBER]} Example: ${request.application.team[0]} |
Gets the value of the team identifier in the specified index for the application identified for this request. |
${request.application.token[NUMBER]} Example: ${request.application.token[1]} |
Gets the value of the token identifier in the specified index for the application identified for this request. |
${request.application.username[NUMBER]} Example: ${request.application.username[0]} |
Gets the value of the username identifier in the specified index for the application identified for this request. |
${request.application.wssUsername[NUMBER]} Example: ${request.application.wssUsername[0]} |
Gets the value of the wssUsername identifier in the specified index for the application identified for this request. |
${request.application.headers.HEADER_NAME} Example: ${request.application.headers.Accept} |
Gets the value of the header name for the headers identifier configured in the application identified for this request. |
${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. |
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:
Simple aliases can be accessed across all stages using variable framework. For example: ${simpleAlias}.
The existing custom and system context variables are now accessible using variable framework. As part of variable framework, the custom context variables that were defined using ctxVar IS service are merged into custom variables. The syntax for accessing the system context variables or custom context variables using variable framework is similar to the custom variables. Example : ${variableName}. For details on how the system and custom context variables were declared in API Gateway version 10.5, see Conditional Routing.
NoteAs like the earlier versions of API Gateway, you can also define and access the custom-context variable or custom-variable using the ctxVar IS Service. For details, see The API for Context Variables.Both system context variables and custom variables (that includes custom context variables) are accessible across all policy parameters that support variables.
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:
External endpoint: Use this custom extension when you have an external endpoint exposed, which can be configured and invoked during any stage in API processing.
For example, if a native API expects the request in a certain format and the client application sends the request in a different format, you can add a custom extension to modify the incoming request to the required format before sending it to the native API.
AWS Lambda: Use this custom extension to invoke an Amazon Web Services (AWS) Lambda function and use the business logic built-in the Lambda function in any stage of API processing.
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
Ensure you have the external endpoint URL to be invoked during API processing using a custom extension.
Click APIs on the title navigation bar.
Click the required API.
The API details page appears.Click Edit.
Select Policies.
Click Required Policy stage > Custom Extension.
This adds the custom extension policy where you can configure the required properties.Click to open the policy properties section in a full page.
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 .
- 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.
Click Custom Action.
Select External endpoint in the custom extension Type field.
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.
Configure the custom properties of the custom extension as required.
For details about the custom extension properties and their descriptions, see Custom Extension Properties.Click Save.
The API is saved with the added custom extension.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
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.Configure AWS alias.
For details on how to configure an AWS alias, see Configuring an AWS Alias.Click APIs on the title navigation bar.
Click the required API.
The API details page appears.Click Edit.
Select Policies.
Click Required Policy stage > Custom Extension.
This adds the custom extension policy where you can configure the required properties.Click to open the policy properties section in a full page.
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 .
- 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.
Click Custom Action.
Select AWS Lambda in the custom extension Type field.
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:
Configure the custom properties of the custom extension as required.
For details about the custom extension properties and their descriptions, see Custom Extension Properties.Click Save.
The API is saved with the added custom extension.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
Click APIs on the title navigation bar.
Click the required API.
The API details page appears.Click Edit.
Select Policies.
Click Required Policy stage > Custom Extension.
This adds the custom extension policy where you can configure the required properties.Click to open the policy properties section in a full page.
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 .
- 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.
Click Custom Variable.
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.
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 asSOAP_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/
.Click Save.
The API is saved with the added custom extension.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:
|
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.
|
Query Parameters | Provide the following information, if you want to configure query parameters you need to send to the custom extension.
|
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 {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.
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.
|
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 |
|
paramType |
|
queryType |
|
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}
.
${paramStage.paramType.paramName}
You can use this syntax to access map types, such as query, headers, and path. Example: ${paramStage.paramType.queryType[queryValue]}
This syntax can be used to query a paramType. Examples:
${request.payload.xpath[//ns:emp/ns:empName]}
Where “${response.payload.jsonPath[$.cardDetails.number]}
Where ${request.payload.regex[[0-9]+]}
Where ${paramStage[stepName].paramType.paramName]}
You can use this syntax to access header or payload from the response of the custom extension in the response processing step.
You can define your own variables in the Transformation variables field in the response processing step.
Example:
${request.query.var1}
, ${response.header.Content-Type}
, ${request.path.name}
.
//ns:emp/ns:empName
” is the XPath to be applied on the payload if contentType is application/xml, text/xml, or text/html.
$.cardDetails.number
is the jsonPath to be applied on payload if contentType is application/json or application/json/badgerfish.
[0-9]+
is the regular expression to be applied on the payload if contentType is text/plain.
xpath
and jsonPath
are applicable only to payload, regEx
can be used with both payload
and path
.Example:
Variable: ${response.headers.id}
Value: ${response[customExtension].payload.jsonPath[$.id]}
This transformation adds a header to the response with name id and its value is derived from the json payload that is sent from the external callout as per the json path.
${key}
, ${value}
. The custom transformation variables that you define are available in subsequent steps.
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:
When the API Provider wants to read the contents of the request and response to do audit logging, or trigger a notification based on the contents of the request.
When the API Provider wants to modify the request before forwarding the request to native API as the native API wants to identify all incoming requests from API Gateway. In such case the provider can configure the Request transformation policy to add a header to all requests before they get routed to the native API.
Pre-Requisites
Install API Gateway advanced edition 10.2 or higher.
Basic understanding of API Gateway and policy enforcement.
Ensure that you have the Manage API privilege.
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:
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.
The client sends the request to API Gateway.
API Gateway applies the transformations configured by the API Provider and transforms the incoming request.
API Gateway sends the transformed request to the native API.
Native API processes the transformed request and sends the response to API Gateway.
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:
Click APIs in the title navigation bar.
A list of available APIs appears.Select a Rest API from the list of APIs and click Edit.
Select Policies > Request Processing > Request Transformation.
The Request Transformation details page appears.In the Condition section, select OR.
The configured transformation is applied when at least one of the conditions is satisfied.
NoteThe condition can also be set to AND operator. The configured transformation is applied only when all the set conditions are satisfied.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.
Select Transformation Configuration > Header/Query/Path transformation.
The Header/Query/Path transformation details page appears.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.
NoteFor details about the variables available in API Gateway, see Variables Available in API Gateway.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.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:
Click Add Condition and provide the following information and click .
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:
You can add multiple variables and corresponding values by clicking . 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:
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:
|
Transformation Metadata: Specifies the metadata for transformation of the incoming requests. For example, the namespaces configured in this section can be used when you provide the syntax for XPath {request.payload.xpath[//ns:emp/ns:empName]} | |
Namespace | Specifies the namespace information to be configured for transformation.
Provide the following information:
|
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:
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.
The client sends the request to API Gateway.
API Gateway forwards the request to native API.
Native API processes the request and sends response to API Gateway.
API Gateway applies the transformations configured by the API Provider and transforms the outgoing response.
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:
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.
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.
NoteThe 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:Variable:
${request.headers.requestOrigin}
Value: APIGateway
NoteFor details about the variables available in API Gateway, see Variables Available in API Gateway.
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.
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.
NoteThe 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}
.
NoteFor 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.
- Code: 301
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:
Click Add Condition and provide the following information and click .
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:
You can add multiple variables and corresponding values by clicking . 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:
|
Payload Transformation | Specifies the payload transformation to be configured for the responses received from the native API.
Provide the following information:
|
Transformation Metadata. Specifies the metadata for transformation of the responses received from the native API. For example, the namespaces configured in this section can be used when you provide the syntax for XPath {response.payload.xpath[//ns:emp/ns:empName]} | |
Namespace | Specifies the namespace information to be configured for transformation.
Provide the following information:
|
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 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:
Set, get, declare, and remove custom context variables.
Set and get the predefined context variables. (It is not allowed to declare or remove the predefined context variables.)
API Gateway provides the following JAVA services, which are defined in the class ISMediatorRuntimeFacade.java:
pub.apigateway.ctxvar:getContextVariable
pub.apigateway.ctxvar:setContextVariable
pub.apigateway.ctxvar:declareContextVariable
pub.apigateway.ctxvar:removeContextVariable
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:
set or get the entire structure.
To set the entire structure, you must:
Set the
varName
parameter inpub.apigateway.ctxvar:setContextVariable
toPROTOCOL_HEADERS
.Use the method
ISMediatorRuntimeFacade.setContextVariableValue()
.
To get the entire structure, you must:
Set the varName parameter in
pub.apigateway.ctxvar:getContextVariable
toPROTOCOL_HEADERS
.Use the method
ISMediatorRuntimeFacade.getContextVariableValue()
.
If the varName is set to PROTOCOL_HEADERS, you get or set the entire IData structure containing all of the transport headers. The key is the transport header name (for example, Content-Type) and the value is a String. The IData object for PROTOCOL_HEADERS contains a set of string values where each IData string key matches the header name in the transport headers map. The set of possible keys includes the HTTP v1.1 set of headers as well as any custom key-value pairs you might have defined.
Alternatively, you can set the varName parameter to address a specific element in the array. For example, setting it to PROTOCOL_HEADERS[Content-Type] would apply to the Content-Type transport header.
set or get a nested value.
Set a nested value in one of the following ways:
Set the
varName
parameter inpub.apigateway.ctxvar:setContextVariable
toPROTOCOL_HEADERS[arrayElement]
, where[arrayElement]
refers to a specific element. For example,PROTOCOL_HEADERS[Content-Type]
(to indicate the first array element in the set).Alternatively, use the method
ISMediatorRuntimeFacade.setContextVariableValue()
. Use this method only if you are writing a JAVA service and you want to access it through the JAVA source code.
Get a nested value in one of the following ways:
Set the
varName
parameter inpub.apigateway.ctxvar:getContextVariable
toPROTOCOL_HEADERS[arrayElement]
, where[arrayElement]
refers to a specific element. For example,PROTOCOL_HEADERS[Content-Type]
(to indicate the first array element in the set).Alternatively, use the method
ISMediatorRuntimeFacade.getContextVariableValue()
. Use this method only if you are writing a JAVA service and you want to access it through the JAVA source code.
You can set or get a nested value inside PROTOCOL_HEADERS through an additional keyName. In this case, the object reference is not an IData object. For PROTOCOL_HEADERS, the keyName must match the transport header name in a case-sensitive manner (for example,
PROTOCOL_HEADERS[Content-Type]
orPROTOCOL_HEADERS[Authorization]
). In this case, the Serializable value will be a string.
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.
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:
After declaring the context variable, you can use the setContext variable to set a value on the context variable.
You do not need to declare the following kinds of context variables:
The predefined context variables provided by API Gateway. If you attempt to declare an existing predefined context variable, an error will occur.
Any custom context variable that you define in a routing rule that you create in the context-based routing step.
Any custom context variables that you explicitly declare in source code using the API will have a declaration scope of SESSION.
Any custom context variable’s state that is defined during the inbound request processing steps will still be available during the outbound response processing steps.
All context variable values are typed as either
string
orint
(excluding the PROTOCOL_HEADERS variables, which are of the typeIData
).Valid names should be upper case (by convention) and must be a valid JAVA Identifier. In general, use alpha-numerics, $ or _ symbols to construct these context names. Names with punctuation, whitespace or other characters will be considered invalid and will fail deployment.
All custom context variables must be declared in a custom namespace that is identified by using an mx prefix (for example,
mx:CUSTOM_VARIABLE
).To reference a custom context variable in a flat string, you need to prepend a $ symbol to the context variable name to indicate that variable’s value should be referenced. Think of this usage as being similar to the & address operation for C variables.
An expression that references a custom context variable might look like this
$mx:TAXID=1234 or $mx:ORDER_SYSTEM_NAME="Pluto"
Notice that the values of the data type “int” are not enclosed in quotation marks, while the values of the data type “string” are. The quotation marks are only needed if a context variable expression (as opposed to a reference) is defined.
Referencing an undefined context variable does not result in an error.
Once a variable has been declared it cannot be declared again.
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.
- 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
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
Clicking on the customName
pipeline variable displays the name.
Step 3. Displaying the value of customName
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
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
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
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
Clicking on the customName
pipeline variable will display the name.
Step 3. Displaying the value of customName
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
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
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
Click APIs in the title navigation bar.
Select the required API.
Click the Policies tab.
Select the policy stage and the required policy.
The policy is displayed in the infographic with its properties displayed in properties section.Provide the properties for the selected policy.
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 |
---|---|
Policy is applied from a global policy. This policy is applicable across all resources / methods / operations of all APIs. | |
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. | |
Policy is applied for the API’s scope. This policy is applicable across a set of resources / methods / operations of that particular API. | |
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
Click APIs in the title navigation bar. A list of all registered APIs appears.
Select the required API.
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. The Identify and Authorize Application policy, always, has the Identification Type set to API Key.
Click . 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
Click APIs in the title navigation bar.
Select the required API.
Click the Policies tab.
Select the policy stage, and the required policy.
The Infographic view displays policies configured for the API.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.
Click Save.
Aliases
Creating a Simple AliasCreating an Endpoint AliasCreating an HTTP Transport Security AliasCreating a SOAP Message Security AliasCreating a webMethods Integration Server Service AliasCreating an XSLT Transformation AliasSupported Alias and Policy CombinationsAn 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:
- Simple alias
- Endpoint alias
- HTTP transport security alias
- SOAP message security alias
- webMethods IS Service alias
- XSLT Transformation 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
Expand the menu options icon , in the title bar, and select Aliases.
Click Create alias.
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. Click Technical information and specify a value in the Default value field.
NoteYou can specify multiple email addresses, if you are creating an email alias, for example, abc@gmail.com, test@gmail.com, and so on.Specify a stage, if you want the alias to be applicable to a specific stage.
Click Save.
NoteFor 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} 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
Expand the menu options icon , in the title bar, and select Aliases.
Click Create alias.
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. 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: - 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.
- 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.
- 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. - 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: - 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.
- 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.
- 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. - 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. 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:
HTTP Basic authentication
OAuth2 authentication
NTLM authentication
Kerberos authentication
JWT authentication
To create an HTTP transport secure alias
Expand the menu options icon , in the title bar, and select Aliases.
Click Create alias.
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. 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. Specify a stage, if you want the alias to be applicable to a specific stage.
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
Expand the menu options icon , in the title bar, and select Aliases.
Click Create alias.
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. 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. 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
Expand the menu options icon , in the title bar, and select User management.
Click Create alias.
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. 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. 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
Expand the menu options icon , in the title bar, and select User management.
Click Create alias.
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. Click Technical information and browse and select an XSLT style sheet in the Select transformation file field.
Specify a stage, if you want the alias to be applicable to a specific stage.
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:
Simple alias
Endpoint alias
HTTP transport security alias
SOAP message security alias
webMethods IS Service alias
XSLT Transformation alias
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:
|
Content-based Routing | In the default and custom Route To rule definitions:
|
Conditional Routing | In the default and custom Route To rule definitions:
|
Load Balancer Routing | In the Route To rule definition:
|
Dynamic Routing | In the default and custom Route To rule definitions:
|
Log Invocation | In the Email Destination section:
|
Monitor Performance | In the Email Destination section:
|
Monitor SLA | In the Email Destination section:
|
Traffic Optimization | In the Email Destination section:
|
Endpoint Alias
Policy Name | Policy Parameter Name |
---|---|
Straight Through Routing | In the Straight Through Routing definition:
|
Content-based Routing | In the default and custom Route To rule definitions:
|
Conditional Routing | In the default and custom Route To rule definitions:
|
Load Balancer Routing | In the Route To rule definition:
|
Dynamic Routing | In the default and custom Route To rule definitions:
|
HTTP Transport Security Alias
Policy Name | Policy Parameter Name |
---|---|
Outbound Authentication - Transport | In the Authentication scheme:
|
SOAP Message Security Alias (Applicable only for SOAP APIs)
Policy Name | Policy Parameter Name |
---|---|
Outbound Authentication - Message | In the Authentication scheme:
|
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
|
Response Transformation (Response Processing) | Transformation Configuration
|
Global Policies
Global Policy MatrixCreating a Global PolicyModifying the Scope of a Global PolicyRefining the Scope of a Global PolicyAssociating Policies to a Global PolicyConfiguring Properties for a Global PolicyViewing List of Global Policies and Policy DetailsModifying Global Policy DetailsActivating a Global PolicyDeactivating a Global PolicyDeleting a Global PolicyCopying a Global PolicyExporting Global PoliciesGlobal 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.
Stages | Policies |
---|---|
Transport | Note: Software AG recommends to create a separate policy for each API type. |
Identity & Access |
|
Request Processing |
|
Routing |
|
Traffic Monitoring |
|
Response Processing |
|
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:
Create a new global policy: During this step, you specify the basic details of the global policy.
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.
Configure the policies: During this step, you associate one or more policies, and assign values to each of the associated policy’s properties.
Activate the policy: During this step, you put the new global policy into effect.
To create a global policy
Click Policies in the title navigation bar.
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.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.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. .
Click Continue to filters >. Alternatively, you can click Filters in the left navigation panel.
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.
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.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: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.
Click Continue to policy configuration>. Alternatively, you can click the Policy configration tab.
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.
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
Click Policies in the title navigation bar.
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.Select the required policy.
The Global Policy details page appears.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.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.
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:
Match strings are not case-sensitive. If you define a filter for names that start with
ABC
it will select names startingabc
andAbc
.Wildcard characters are not supported. That is, you cannot use characters such as * or % to represent any sequence of characters. These characters, if present in the match string, are simply treated as literal characters that are to be matched.
Filtering by HTTP Methods (Applicable only for REST APIs)
- You can optionally restrict a policy to specific HTTP methods of the REST APIs by specifying the following options - GET, POST, PUT, DELETE, PATCH, and HEAD.
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
Click Policies in the title navigation bar.
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.Select the required policy.
The Global Policy details page appears.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.Click Filters.
To filter by API types, select the API types by which you want to filter APIs.
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.
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.
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
Click Policies in the title navigation bar.
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.Select the required policy.
The Global Policy details page appears.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.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
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.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.
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.
Click Save.
Click 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
Click Policies in the title navigation bar.
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.Select the required policy.
The Global Policy details page appears.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.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
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.
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.
NoteRequired properties are marked with an asterisk.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.
Click Save.
Click 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
Click Policies in the title navigation bar.
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.
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:
You will not be allowed to save the policy unless all of its properties have been set.
On successful modification of the policy details for an active global policy, the policy changes apply with immediate effect in all the active APIs that are applicable for this global policy.
You will not be allowed to remove an individual policy (for example, Identify and Authorize Application) from the active global policy, if the global policy is already applied to an active API, and if the Identify and Authorize Application is a dependent policy for another policy (for example, Traffic Optimization) that is applied for the API.
If modification of the policy details for an active global policy fails, API Gateway issues an error message with details of the incompatible or conflicting policies.
To modify the properties of a global policy
Click Policies in the title navigation bar.
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.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.
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.On the Policy Details tab, modify the basic properties, selection criteria, and the applicable APIs as necessary.
On the Policy Configuration tab, modify the policy list and the policy’s configuration properties as necessary.
When you have completed the required modifications in the Global Policy details page, click Save to save the updated policy.
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:
When a global policy becomes active, API Gateway begins enforcing it immediately in all the applicable APIs that are currently in the Active state. You can suspend enforcement of a policy by switching it to the Inactive state as described in Deactivating a Global Policy.
Activation of a global policy fails if there is a conflict in the effective policy validation in at least one of the active APIs that are applicable for this policy. API Gateway reports the conflict, and the global policy can only be activated when the conflict is resolved.
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 |
---|---|
Policy is active. | |
Policy is inactive. |
The activation state of a policy is also reported in the Global Policy Details page.
To activate a global policy
Click Policies in the title navigation bar.
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.Select the required policy.
The Global Policy details page appears.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:
- Deactivation of a global policy fails if there is a conflict in the effective policy validation in at least one of the active APIs that are applicable for this policy. API Gateway reports the conflict, and the global policy can only be activated when the conflict is resolved.
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 |
---|---|
Policy is active. | |
Policy is inactive. |
The deactivation state of a policy is also reported in the Global Policy Details page.
To deactivate a global policy
Click Policies in the title navigation bar.
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.Select the required policy.
The Global Policy details page appears.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:
The policy must not be in-progress.
The policy must be inactive.
To delete a global policy
Click Policies in the title navigation bar.
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.Click the Delete 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.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:
When API Gateway creates a copy of a policy, the new copy of the policy is identical to the original one.
Like all new policies, the copied policy is marked as Inactive.
There is no expressed relationship between the copy and the original policy (that is, API Gateway does not establish any type of association between the two policies).
In general, a copied policy is no different from a policy that you create from scratch.
To copy a global policy
Click Policies in the title navigation bar.
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.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.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. Click Copy to save the new policy.
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.
To export the global policies
Click Policies in the title navigation bar.
Select Global Policies.
Click 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 and select Export from the drop-down list.
The browser prompts you to either open or save the export archive.
Select the appropriate option and click OK.
Scope-level Policies
API ScopesCreating an API ScopeViewing List of API Scopes and Scope DetailsModifying API Scope DetailsDeleting an API ScopeCreating a Scope-level PolicyViewing List of Scope-level Policies and Policy DetailsModifying Scope-level Policy DetailsDeleting a Scope-level PolicyExample - Usage Scenarios of API ScopesYou 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.
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:
For a policy (for example, Identify & Authorize) that can appear only once in an API, if the same policy is already applied through the API details page, API Gateway prompts you with a warning message that the scope-level policy takes precedence over the API-level policy, and is enforced on the API at run-time.
For a policy (for example, Monitor SLA) that can appear multiple times in an API, if the same policy is already applied to the API through a global policy, API Gateway prompts you with a warning message that the global policy takes precedence over the scope-level policy, and is enforced on the API at run-time.
If a resource or method or operation has the same policy (for example, Require HTTP / HTTPs) applied through different scopes, API Gateway prompts you with an error message and sets the focus to the conflicting policies. You must remove the required policy from the individual scope(s) to resolve the conflicts.
API Gateway supports scope-level policies only for the following stages:
Identify and Access: All policies in this stage are supported.
Request Processing: Only Data Masking policy in this stage is supported.
Traffic Monitoring: All policies in this stage are supported.
Response Processing: Only Data Masking policy in this stage is supported.
Error Handling: Only Data Masking policy in this stage is supported.
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.
To create a scope
Click APIs in the title navigation bar.
A list of APIs available in API Gateway appears.Click the name of the required API.
This opens the API details page.Click Edit.
If the API is active, API Gateway prompts you to deactivate it.Click the Scopes tab.
This displays a list of scopes available in the API.In the List of scopes section, click Add scope.
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. 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.Applicable only for SOAP APIs. In the Operations section, select the operations you want to associate to this scope.
Click Save.
The scope is created and listed in the List of scopes section.
Post-requisites:
Activate the API when you are ready to put it into effect.
To apply and configure policies for this API scope, see Creating a Scope-level Policy.
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
Click APIs in the title navigation bar.
A list of APIs available in API Gateway appears.Click the name of the required API.
This opens the API details page.Click the Scopes tab.
This displays a list of scopes available in the API.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
Click APIs in the title navigation bar.
A list of APIs available in API Gateway appears.Click the name of the required API.
This opens the API details page.Click Edit.
If the API is active, API Gateway displays a warning message to let you know that the API is active.Click the Scopes tab.
This displays a list of scopes available in the API.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.
Modify the basic properties, applicable resources, methods, or operations of the scope.
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
Click APIs in the title navigation bar.
A list of all registered APIs appears.Click the name of the required API.
This opens the API details page.Click Edit.
If the API is active, API Gateway displays a warning message to let you know that the API is active.Click the Scopes tab.
This tab displays a list of scopes available with the API.In the List of scopes section, locate the name of the scope you want to delete.
Click the Delete () icon next to the scope name.
Click Yes in the confirmation dialog.
The scope is removed from the List of scopes section.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
Click APIs in the title navigation bar.
This displays a list of APIs available in API Gateway.Click the name of the required API.
This opens the API details page.Click Edit.
If the API is active, API Gateway displays a warning message to let you know that the API is active.Click the Policies tab.
This displays a list of scopes and policies available in the API.In the API Scope box, select the scope for that you want to create a policy.
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.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.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.
NoteRequired properties are marked with an asterisk.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.Set the properties of the displayed policy, and then click OK.
To exit out of full-screen mode, click the Minimize icon.Click Save to create the new scope-level policy.
Click 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
Click APIs in the title navigation bar.
This displays a list of APIs available in API Gateway.Click the name of the required API.
This opens the API details page.Click the Policies tab.
This displays a list of scopes and policies available in the API.In the API Scope box, select the scope whose policy details you want to examine.
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.
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.
Click 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
Click APIs in the title navigation bar.
This displays a list of APIs available in API Gateway.Click the name of the required API.
This opens the API details page.Click Edit.
If the API is active, API Gateway displays a warning message to let you know that the API is active.Click the Policies tab.
This displays a list of scopes and policies available in the API.In the API Scope box, select the scope whose policy details you want to modify.
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.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.Modify the properties of the displayed policy, and then click OK.
To exit full-screen mode, click the Minimize icon.When you have completed the required modifications for the scope-level policy, click Save to save the updated scope-level policy.
Click 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:
- When a scope is deleted from the API details, API Gateway removes the policies that were associated with the deleted scope.
To delete a scope-level policy
Click APIs in the title navigation bar.
A list of all registered APIs appears.Select the required API.
This opens the API details page.Click Edit.
If the API is active, API Gateway displays a warning message to let you know that the API is active.Click the Policies tab.
A list of scopes and policies available with the API appears.In the API Scope box, select the scope whose policy you want to remove.
In the Infographic section, click the x icon in any individual policy to remove that particular policy from the scope.
When you have removed the policy, click Save to save the updated scope-level policy.
Click 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:
Global Policy Enforcement
Method-level Policy Enforcement (REST APIs) -OR- Operation-level Policy Enforcement (SOAP APIs)
Resource-level Policy Enforcement (REST APIs)
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
Global Policy: Not applicable
Method-level Policy: Not applicable
Resource-level Policy(s): Inbound Authentication - Transport
API-level Policy: Identify and Authorize Application policy with HTTP Basic Authentication
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:
Inbound Authentication - Transport
Identify and Authorize Application policy with HTTP Basic Authentication
Scenario B: Invoke POST method on the Resource C: /phones/orders/{order-id}/paymentdetails in WRITE Scope
Global Policy: Not applicable
Method-level Policy(s): (1) Identify and Authorize Application policy with API Key (2) Traffic Optimization
Resource-level Policy(s): Inbound Authentication - Transport
API-level Policy: Identify and Authorize Application policy with HTTP Basic Authentication
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:
Inbound Authentication - Transport
Identify and Authorize policy with API Key
Traffic Optimization
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
Global Policy: Identify and Authorize Application policy with Hostname Address
Method-level Policy(s): (1) Identify and Authorize policy with API Key (2) Traffic Optimization
Resource-level Policy(s): Inbound Authentication - Transport
API-level Policy: Identify and Authorize policy with HTTP Basic Authentication
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
Identify and Authorize policy with Hostname Address
Traffic Optimization
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.
Global Policy: Not applicable.
Method-level Policy(s):
a. Identify and Authorize policy with API Key
b. Identify and Authorize policy with IP Address Range
c. Traffic Optimization
Resource-level Policy(s): Inbound Authentication - Transport
API-level Policy: Identify and Authorize policy with HTTP Basic Authentication
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:
Option 1: Remove the existing association between the POST method and the WRITE Scope or UPDATE Scope through the API Scope details.
Option 2: Delete the WRITE Scope or UPDATE Scope.
Option 3: Remove the Identify and Authorize Application policy from the WRITE Scope or UPDATE Scope.
Policy Templates
Creating a Policy TemplateAssociating Policies with a Policy TemplateConfiguring Properties for a Policy TemplateViewing List of Policy Templates and Template DetailsModifying Policy Template DetailsDeleting a Policy TemplateCopying a Policy TemplateApplying a Policy Template on the API Details PageModifying a Policy Template on the API Details PageSaving Policy Definition of an API as Policy TemplatePolicy 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:
Create a new policy template: During this step, you specify the basic details of the policy template.
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
Click Policies in the title navigation bar.
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.In the Policies page, click the Create Policy Template button.
This opens the Create Policy Template page with the default Policy Details tab.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. Click Continue to policy configuration.
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.
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
Click Policies in the title navigation bar.
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.Select the required template.
The Policy Template details page appears.Click Edit.
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
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.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.
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.
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.
Click 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
Click Policies in the title navigation bar.
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.Select the required template.
The Policy Template details page appears.Click Edit.
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
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.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.
NoteRequired properties are marked with an asterisk.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.
After you configure the properties for all the policies in the Infographic section, click Save to save the updated policy template.
Click 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
Click Policies in the title navigation bar.
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.
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
Click Policies in the title navigation bar.
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.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.
Click Edit.
On the Policy Details tab, modify the basic properties of the policy as necessary.
On the Policy Configuration tab, modify the policy list and the policy’s configuration properties as necessary.
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.
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
Click Policies in the title navigation bar.
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.Click the Delete () icon for the required template.
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:
When API Gateway creates a copy of a policy template, the new copy of the policy template is identical to the original one.
There is no expressed relationship between the copy and the original policy (that is, API Gateway does not establish any type of association between the two policy templates).
In general, a copied policy template is no different from a policy template that you create from scratch.
To copy a policy template
Click Policies in the title navigation bar.
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.Click the Copy icon for the required template.
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. Click Copy to save the new policy template.
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
Click APIs in the title navigation bar.
A list of all registered APIs appears.Select the required API.
Click Edit.
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
Click Apply template located in the lower right-corner of the Infographic section.
This opens the Apply template dialog box.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.Select one or more policy templates that you want API Gateway to execute at run-time.
Click Next. You must have at least one template selected to use the Next button.
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.
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.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
Click APIs in the title navigation bar.
A list of all registered APIs appears.Select the required API.
Click Edit.
If the API is active, API Gateway displays a warning message to let you know that the API is active.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
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.
NoteRequired 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.
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.Set the properties of the displayed policy, and then click OK.
To exit full screen mode, click the Minimize icon.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
Click APIs in the title navigation bar.
A list of all registered APIs appears.Select the required API.
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
Click Save as template located in the lower right-hand corner of the Infographic section.
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. Click Save.
Change Ownership of Assets
How Do I Change the Ownership of an API?How Do I Change the Ownership of an Application?How Do I Change the Ownership of Multiple 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:
API Gateway advanced edition version 10.5 or higher installed.
Basic understanding of API Gateway and its related components like the API Gateway user interface.
Change owner or team privilege.
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
Log on to API Gateway as a user with the change owner privilege.
Click APIs on the title navigation bar.
Click petstore.
The API details page appears. The owner of the API petstore is user1 as displayed in the Basic information section.
Click change.
Select user2 from the list and click .
The change approval process is initiated.
NoteIf the approval flow is not configured, the owner of the API changes to user2 and a success message appears. Skip to step 8.An approval request is sent to the approver.
The approver approves the request that resides in the Pending Requests section of the API Gateway UI.
NoteThe 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.Click Change ownership request details to view the request details. The Request details dialog box appears.
The approval notification is sent to the requester.
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
Log on to API Gateway as a user with the change owner privilege.
Click Applications on the title navigation bar.
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.Click .
Select Team.
Select DevTeam from the list and click .
The change approval process is initiated.NoteIf the approval flow is not configured, the owner of the application changes and a success message appears. Skip to step 8.An approval request is sent to the approver.
The approver approves the request that resides in the Pending Requests section of the API Gateway UI.
NoteThe 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.
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
- 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:
assetType. Specifies the asset type for which you want to change the owner. Available values are API, APPLICATION, or the wildcard *. The wildcard * specifies all the assets, APIs and applications owned by the user specified in currentOwner.
assetIds. Specifies the ID of the assets specified in assetType.
NoteThis is optional. assetIds is not required if you specify currentOwner.currentOwner. Specifies the user name of the owner of the assets specified in the assetType field.
NoteIf both currentOwner and assetIds are specified, both are validated. For example, consider user1 and user2 are owners of assetID1 and assetID2 respectively. In the request payload, if you include assetID1 and assetID2 in the assetIds field and user1 in the currentOwner field, then only assetID1 ownership changes.newOwner. Specifies the user name of the user who would be the new owner of the assets specified.
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.
- 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.
- The approver approves the request in the Pending Requests section of the API Gateway UI.
The approval notification is sent to the requester.
- The owner of the assets is changed from user1 to user2.
Debugging API
How do I enable tracing?How do I filter the runtime request?How do I view the trace details?How do I inspect failed runtime requests using tracer?How do I import runtime requests?How do I export or download runtime requests?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
- the list of policies that were invoked in each stage.
- time taken to execute the stage and its corresponding policies.
- policy configured at the time of invocation.
- values that were passed as input before the execution of the policies and values that were transformed at the end of the policy execution.
- conditions and transformations that were applied and performed at the time of invocation.
- server log captured at the time of invocation.
Important considerations when you trace an API:
- When you create a new API version from an API for which tracing is enabled, by default tracing is disabled in the newly versioned API.
- When you import an API with the Overwrite option selected as All or Custom - API, and if the API already exists after you import the API, by default the trace is disabled. You have to enable trace explicitly.
- When you promote an API with the option Overwrites assets except alias that already exist on the selected target stages selected, by default after you promote the API to the target instance, the trace is disabled. You have to enable trace explicitly.
- API Gateway does not support tracing for threat protection policies and rules.
- API Gateway does not support tracing for Microgateway groups.
The following policies are covered as part of trace API:
- Transport
- Enable HTTP/HTTPS
- Set Media Type
- Identify & Access
- Authorize Users
- Identify & Authorize
- Custom Extension
- Request Processing
- Invoke webMethods IS
- Request Transformation
- Data Masking
- Custom Extension
- Routing
- Straight Through Routing
- Custom HTTP Header
- Outbound Auth - Transport
- Custom Extension
- Response Processing
- Invoke webMethods IS
- Response Transformation
- CORS
- Data Masking
- Custom Extension
- Error Handling
- Data Masking
- Custom Extension
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:
- Manage APIs privilege.
- activated the API before you enable the tracer.
To enable tracing
Click APIs in the title navigation bar.
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.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.Click the Tracer tab to view the trace details.
The Trace API page displays the Runtime events, Policies applied, and Event tracer details sections.NoteWhen 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
Click the Tracer tab.
The Trace API page displays the Runtime events , Policies applied , and Event tracer details sections.In the Runtime events section, click to filter the runtime events.
The Apply filter pop-up window displays.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:
- Manage APIs and Activate APIs privileges.
- invoked the API after you have enabled the tracer.
To view the trace details
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.
NoteIf the request and response body has streaming content, the tracer does not capture the streaming content even if you have enabled the tracer.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.
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.NoteThe 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
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.
NoteIf the request and response body has streaming content, the tracer does not capture the streaming content even if you have enabled the tracer.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.
NoteIn 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.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.
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
Click the Tracer tab.
The Trace API page displays the Runtime events, Policies applied, and Event tracer details sections.In the Runtime events section, click to import the archived runtime request.
The Import and view events pop-up window displays.Browse the runtime request file that you want to import.
NoteMake sure the file that you import does not exceed 50 MB.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
Click the Tracer tab.
The Trace API page displays the Runtime events, Policies applied, and Event tracer details sections.In the Runtime events section, select the runtime event that you want to export.
- Click to export the runtime request. The selected request is downloaded to your local machine in a predefined location.
API Mashups
Creating an API MashupServers 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.
The APIs that are included in an API mashup (participating APIs) can be connected to each other in the following ways:
API chaining: Two or more participating APIs are connected and invoked in a sequence—one after the other.
API aggregation: Two or more participating APIs are connected to a common aggregator step. The aggregator step captures the response of the aggregated APIs. The aggregator step enables you to:
Collate the responses and pass to the next step.
Process the responses and pass the processed data to the next step.
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
An API mashup allows you to orchestrate multiple resources and methods and expose the behavior as a single service. In a regular method that is not a mashup, API Gateway applies all the enforced policies and then routes the request to the native endpoint. In the case of a mashup, API Gateway still applies all the enforced policies in the request flow till routing; but thereafter, it starts the orchestration flow defined in the mashup. After the orchestration flow ends, all the policies defined for that method are applied in the response flow—in the same way as a regular method.
API mashups are defined at the method level. You can edit any REST API and define a mashup for one or more methods within it.
You can include any REST API defined within API Gateway in the mashup.
The entire framework that API Gateway provides to a regular REST API method is available to an API mashup method. Therefore, you can utilize query parameters, path parameters, aliases, variables, payload transformations using XSLT transforms, transformations using webMethods IS services, and custom pipeline variables.
Considerations for Creating an API Mashup
By default, the policies of an API that is participating in an API mashup are not enforced when it is invoked within the API mashup. However, if you select the Should execute Outbound policies option, the outbound security policies of the participating API are enforced in the context of the API mashup.
The following are specific to a mashup step and are not automatically passed from one step to another:
Headers
Query parameters
Path parameters
Payload
However, you can add parameters in a mashup step to access data from any of the previous steps or another source. An exception to this rule is the first step (the first participating service) in a mashup, which receives the complete request sent by the client.
A participating API cannot have reverse invoke routing.
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 |
|
paramType |
|
queryType |
|
The following data objects are available to a mashup step:
${paramStage.paramType}
: You can use this syntax to access the following string variables:path
,statusCode
,statusMessage
,httpMethod
. Examples:${request.path}
,${response.statusCode}
.${paramStage.paramType.paramName}
: You can use this syntax to access map types, such as query, headers, and path. Example:${request.query.var1}
,${response.header.Content-Type}
,${request.path.name}
.${paramStage.paramType.queryType[queryValue]}
: This syntax can be used to query a paramType. Examples:${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”, “text/xml”, or “text/html”.${response.payload.jsonPath[$.cardDetails.number]}
where “$.cardDetails.number
” is the jsonPath to be applied on payload if contentType is “application/json” or “application/json/badgerfish”.${request.payload.regex[[0-9]+]}
where “[0-9]+
” is the regular expression to be applied on the payload if contentType is “text/plain”.
NoteWhilexpath
andjsonPath
are applicable only to payload,regEx
can be used with bothpayload
andpath
.${paramStage[stepName].paramType.queryType[queryValue]}
: You can use this syntax to access data in any step. For example, you can use the following syntax to access the payload of a step namedcreateAPI
:${response[createAPI].payload.jsonPath[$.apiResponse.api.id]}
.You can define your own variables using the Custom Pipeline variables field: Examples: ${key}, ${value}. The custom pipeline variables that you define are available in subsequent steps.
Creating an API Mashup
To create a mashup you require:
The API must include the resource and the method in which you want to add the API mashup.
The participating APIs (that you want to include in the mashup) must exist in the API Gateway instance.
To create a mashup in a REST API
Click APIs in the title navigation bar. A list of all registered APIs appears.
Click the required API.
The API details page appears.Click Edit.
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.NoteIf 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.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.Click the toggle button to enable the method in which you want to create the mashup.
NoteIf you use the toggle button and disable a method that has a mashup, the mashup definition for that method is immediately cleared.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: - Namespace Prefix
- Namespace URI
For information about transformation metadata, see Request Transformation.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.NoteIn 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.Click Add aggregator to add an aggregator step.
NoteYou 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.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.
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.
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
NoteIn 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.Add, configure, and connect additional API invocation steps and API aggregator steps as desired.
Click Save.
The mashup is created for the selected method.
SOAP to REST Transformation
Activating SOAP to Rest TransformationModifying the REST Definitions for SOAP OperationsSupported Content-types and Accept HeadersREST API EndpointsSamples for REST RequestLimitationsSOAP 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.
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
Click APIs in the title navigation bar.
Select the required API from the list of available APIs.
The API details page for the selected API appears.
Click Edit.
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.
Click 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.Select the operation to edit the SOAP operations.
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.
- 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.
Click Save.
The API details page for the selected API appears.
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
Click APIs in the title navigation bar.
Select the required API from the list of available APIs.
The API details page for the selected API appears.Click Edit.
Click REST transformation.
A list of SOAP operations already exposed to the consumers as well as to be transformed from SOAP to REST appears.Click 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.Select the operation to edit the SOAP operations.
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. 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 .
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.Click Add Request and provide the schema and a sample for the content-type.
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.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.Click 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.Select the operation to edit the SOAP operations.
Click Save.
The API details page for the selected API appears.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.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 |
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>
/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) |
|
|
Consists of only one element (non-qualified namespaces) |
|
|
Consists of multiple elements |
|
|
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 |
|
|
Consists of only one element and client does not send the Namespace |
|
|
Consists of only one element and the client sends a different namespace to API Gateway |
|
|
Multiple XML elements |
|
|
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 |
or
|
|
Multiple query or path parameters |
or
or
|
|
Hierarchical elements |
|
|
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:
The Multipurpose Internet Mail Extensions (MIME) parts that have a content ID or name that match the elements of type
base64Binary
orhexBinary
in the schema are added as attachments to the outbound request.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
andapplication/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:
When the API provider defines the mapping for the SOAP operation to the REST resource or method, API Gateway allows him to specify either the path and the query parameters or the body but not both. These mappings are used when transforming the incoming REST request to the SOAP request.
If both path and query parameters and body are sent in the incoming REST request, then the path and the query parameters are ignored.
If your REST resource accepts the
text/xml
content-type, then you cannot modify the default resource path and resource name automatically generated by the system. This name must be same as the SOAP operation name. However, this limitation is not applicable for other content-types.The HTTP method filters of the global policy are not applicable to the REST transformed method of the SOAP API.
The REST (REST transformed SOAP operations) resources do not appear as general REST resources when filtered in the Scopes section of the API in API Gateway.
You cannot apply the Inbound Authentication-Message policy to the SOAP operation enabled as REST.
The SOAP services that have Web Services Interoperability Organization (WS-I) non-compliant WSDLs cannot be REST-enabled.
API First Implementation
API First Design using API GatewayAPI First Implementation using Integration ServerAPI First Implementation using a Third-party ServerList of Parameters used in API ImplementationAPIs 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
Ensure that you have the Manage API privilege.
Configure the required Integration Server instances in API Gateway for implementing your APIs.
To adapt API First design using Integration Server
Log on to API Gateway.
Click APIs in the title navigation bar.
A list of all existing APIs appears.Click Create API to create an API with required API documentation.
Click Policies and define required policies for the API.
Click Enable Mockingto mock and generate API mock responses. This step enables the API to send responses to the requests received from consumers.
From the APIs page, click Publish for the APIFirst API.
The Publish API dialog box appears.Select Integration Servers.
The list of configured Integration Servers instances appears.Select the IS1 instance from the list.
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.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
Ensure that you have the Manage API privilege in API Gateway.
Configure a third-party implementation server for implementing your APIs.
To adapt API First design using a third-party implementation server
Log on to API Gateway.
Click APIs in the title navigation bar. A list of all existing APIs appears.
Click Create API to create an API with required API documentation.
Click Policies and define required policies for the API.
Click Enable Mocking to mock and generate API mock responses.
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
POST http://<API Gateway hostname>/rest/apigateway/search
{
"types" : ["api"],
"scope" : [
{
"attributeName" : "maturityState",
"keyword" : "ToBeImplemented"
}
]
}
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. |