Author: Chandrasekaran, Vallab (vac@softwareag.com)
Supported Versions: 10.3 and 10.5. For versions above 10.7, refer this
webMethods API Gateway tutorial
Overview of the tutorial
Despite the Invoke webMethods IS policy in API Gateway helps the API Provider to plugin custom logic, such as the transformation of request and response contents, in the mediation flow of an API, the newly introduced transformation policies in 10.2 provide a better and easy configuration of transformations based on conditions to a greater extent. The Provider doesn't need to create an IS service explicitly, instead, he can use the simple configurations provided in the transformation policies to achieve the same use cases. The conditions could be used to evaluate the values of the contents of request or response like headers, query parameters, path parameters, HTTP method, status code, status message and payload.This gives a hassle-free way of transforming content using the configurations provided in transformation policies. In this tutorial, we shall see how to conditionally transform the contents in a request and/or response, such as headers, query parameters, etc. using Request and Response Transformation policies.
Required knowledge
The reader is expected to have a basic understanding of API Gateway and policy enforcement.
Why?
API Gateway forwards the incoming requests from the client to the native service and forwards the response from the native service back to the client. Now when the API Provider wants to read the contents of the request and/or response to do some audit logging or trigger a notification based on the contents of the request, the Provider can configure the Request or Response transformation policy to read the contents of the request/response using IS Service. In another case, if the API Provider wants to modify the request before forwarding the request to Native service as the native service 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 service.
Prerequisite steps
- Install advanced edition of API Gateway 10.2
Details
Use cases
The following sections explain the use cases of transformation policies in detail.
Use case 1: Request Transformation
The Request Transformation policy can be used 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 below diagram represents the flow of "Request Transformation" policy usage for transforming the request contents.
Design time flow
- The API Provider configures the "Request Transformation" policy in the Request processing stage of API Gateway. The provider configures details about when and how to transform contents such as headers, query parameters, path parameters, payload, HTTP method.
Runtime flow
- The Client sends the request to API Gateway
- API Gateway executes the transformations configured by the API Provider, and transform the incoming request
- API Gateway sends the transformed request to the native service
- Native server processes the transformed request and sends the response to API Gateway
- API Gateway forwards the response to client
Use case 2: Response Transformation
The "Response Transformation" policy can be used to modify the contents of an outgoing response such as headers, payload, status code, status message using the configurations given by the API Provider. The below diagram represents the flow of "Response Transformation" policy usage for transforming the response contents.
Design time flow
- The API Provider configures the "Response Transformation" policy in the Response processing stage of API Gateway. The provider configures details about when and how to transform contents such as headers, status-code, status-message, payload.
Run time flow
- The Client sends the request to API Gateway
- API Gateway forwards the request to native service
- Native service processes the request and sends a response to API Gateway
- API Gateway executes the transformations configured by the API Provider, and transform the response
- API Gateway sends the transformed response to the client
Configuring Transformation policies
In this section lets discuss the details of transformation policies in detail. The transformation policy (Request or Response) contains 3 sections:
- Condition
- Transformation Configuration
- Transformation Metadata
Syntax
We will explain the syntax of various child parameters of the transformation policy in their respective sections. The below table shows the keywords which are used to define those syntaxes.
| Keyword | Usage |
|---|---|
| paramStage |
Defines the stage which we are referring to. Possible values are,
|
| paramType |
Defines the specific parameter of the request/response whose value we are transforming, or evaluating using a condition.
|
| queryType |
Defines the query that can be applied over string elements like payload. Possible values are,
|
Condition
The condition parameter provides you option to execute the transformation when configured conditions evaluate to true. The conditions could be used to evaluate the values of contents of the request/response such as header, query parameters, path parameters, HTTP method, payload, status code, status message. The condition parameter contains the following configurations.
- Choose whether to evaluate the conditions using AND operator or OR operator.
- If AND is chosen, the transformation (configured in Transformation Configuration) is executed only when all conditions evaluate to True.
- If OR is chosen, the transformation (configured in Transformation Configuration) is executed when at least one of the conditions evaluate to True.
- "Add Condition" button which allows you to configure the conditions
When you click on "Add Condition", you can configure the conditions using the following parameters.
Variable
Configure the variable for which the condition is evaluated.
Applicable syntaxes are:
${paramStage.paramType}
- This syntax is applicable only for variables of string type - path, statusCode, statusMessage, httpMethod
- eg: ${request.path}, ${response.statusCode}
${paramStage.paramType.paramName}
- This syntax is applicable for map types (i.e, query and headers) and also applicable for path
- eg: ${request.query.var1} ${response.header.Content-Type} ${request.path.name}
${paramStage.paramType.queryType[queryValue]}
- This syntax is applicable for payload. You can also apply regEx over path.
- Examples
- ${request.payload.xpath[//ns:emp/ns:empName]} → "//ns:emp/ns:empName" is the xpath to be applied on payload if contentType is "application/xml or text/xml or text/html"
- ${response.payload.jsonPath[$.cardDetails.number]} → "$.cardDetails.number" is the jsonPath to be applied on payload if contentType is "application/json or application/json/badgerfish"
- ${request.payload.regex[[0-9]+]} → "[0-9]+" is the regex to be applied on payload if contentType is "text/plain"
${paramStage.paramType.queryType[queryValue] || paramStage.paramType.queryType2[queryValue2] || ...}
- If you want API Gateway to apply xpath, jsonPath, regex based based on Content-Type of the payload, you can use the below common syntax.
- Examples
- ${request.payload.xpath[//ns:emp/ns:empName] || request.payload.jsonPath[$.cardDetails.number]} → This example applies xpath for "application/xml" and jsonPath for "application/json"
- ${request.payload.xpath[//ns:emp/ns:empName] || request.payload.jsonPath[$.cardDetails.number] || request.payload.regex[[0-9]+]} → This example applies xpath for "application/xml" and jsonPath for "application/json" and regex for "text/plain"
Operator
Configure the condition operator.
Possible values are "equals", "Equals Ignore Case", "Not Equals", "Contains", "Exists"
Value
The value with which the variable is evaluated using the conditional operator. (Not applicable for "Exists")
The applicable syntaxes are:
- Just enter the plain value directly. eg: application/json
- ${paramStage.paramType.paramName}
- ${paramStage.paramType.queryType[queryValue]}
- ${paramStage.paramType.queryType[queryValue] || paramStage.paramType.queryType2[queryValue2] || ...} (Applicable only for the payload}
Combinations:
| paramStage |
paramType |
extra parameters |
|---|---|---|
request |
headers | HEADER_NAME |
| query (applicable only for REST) | QUERY_NAME | |
|
path (applicable only for REST)
|
PATH_PARAMETER | |
| regex[REGEX_EXPRESSION] | ||
|
PATH STRING |
||
| httpMethod (applicable only for REST) | - | |
|
payload |
xpath[EXPRESSION] | |
| jsonPath[EXPRESSION] | ||
| regex[EXPRESSION] | ||
|
authorization |
clientId |
|
|
issuer |
||
|
userName |
||
|
authHeader |
||
|
apiKey |
||
|
incomingToken |
||
|
audience (This was introduced to hold the audience value calculated after the authorization process. In case of JWT/OpenID/OAuth2 this would be the "aud" claim. For SAML or another type of authentication, it would be the audience URI. But because of time constraints, it was not populated. In future this would hold the audience of the token.) |
||
|
claims.CLAIM_NAME |
||
| correlationID | ||
|
application |
id | |
| name | ||
| version | ||
| claims.CLAIM_NAME | ||
response |
header | HEADER_NAME |
|
statusCode |
- | |
|
statusMessage |
- | |
|
payload |
jsonPath[EXPRESSION] | |
| regex[EXPRESSION] | ||
|
xpath[EXPRESSION] |
Condition - Example
The conditions configured using "Add condition" are added to the table as shown in the image below.
In the screenshot above, three conditions are configured with OR operator.
- The first condition checks if "Content-Type" header value is equal to "application/json"
- The second condition checks if the value of header named "var1" and query parameter named "var1" are not equal
- The third condition checks that, if the configured value ("Vallab") is the substring of the empName found in the payload after applying the xpath "//ns:emp/ns:empName" to the payload. For example, if "empName" returns "Vallab Chandrasekaran", the condition evaluates to True as "Vallab" is a substring of the value of empName
Transformation Configuration
The transformation configuration contains the following sub-configurations.
Header/Query/Path transformation
In this section, let us see how to do the header, query parameters and path parameter transformation (adding a header or query parameter, modifying the value of a header or query or path parameter, removing a header or query or path parameter) using Transformation policy.
Applicable Types: REST
Applicable Stage: Request Processing
The child parameters of this configuration are,
Add/Modify
This parameter is used to add or modify one or more header, query and path parameters.
The child parameters are:
Variable
The variable which needs to be transformed. Applicable syntaxes are below (applicable paramType is only headers/query/path as we are transforming one or more of these.)
- ${paramStage.paramType.paramName} - applicable for header/query/path
- Example: ${request.headers.Content-Type}
- ${paramStage.paramType} - applicable only for path.
- Example: ${request.path}
Value
The value which needs to be assigned to the variable configured. (All paramType applicable)
The applicable syntaxes are:
- Just enter the plain value directly. eg: application/json
- ${paramStage.paramType.paramName}
- ${paramStage.paramType.queryType[queryValue]}
- ${paramStage.paramType.queryType[queryValue] || paramStage.paramType.queryType2[queryValue2] || ...}
Remove
This parameter is used to remove one or more header and query parameters.
The applicable syntax is ${paramStage.paramType.paramName}.
In the above image, you could see how to add/modify/remove headers, query, path parameters.
Path Transformation - syntaxes and examples
Path transformation can be configured using "Header/Query/Path Transformation" parameter as shown in the above section. Path transformation can be done in many ways using the below syntaxes.
- Modify the entire path and set an absolute value.
- Example: ${request.path} = "/name/sekar/age/27"
- Replace a substring of the path with another value using the path parameter configured in API Gateway
- For example, API Gateway "Resources and Methods" is configured with a resource as "/pet/{petId}", and the path transformation is configured as ${request.path.petId} = "1234". In this example, if the incoming path is "/pet/XYZ", it is replaced as "/pet/1234" irrespective of the value of XYZ
- Replace a substring of the path with another value using the exact match
- Example: ${request.path.name} = "firstName". This example replaces /name in path with /firstName
- Modify the entire path by querying payload using xpath/jsonPath/regEx
- Example: ${request.path} = ${request.payload.xpath[//ns:emp/ns:empName]}
- Applying regular expression over path
- Example: ${request.path.regex[/name/(.)*?/]} = "/name/vallab/". This example replaces "/name/***/" with "/name/vallab/"
- Appending a substring to existing path.
- Example: ${request.path} = ${request.path}/age/27. This example appends '/age/27' to the existing path
Header transformation
In this section, let us see how to do header transformation (adding a header, modifying the value of a header, removing a header) using Transformation policy.
Applicable Types and Stage: Applicable for SOAP (for both Request & Response Processing stages) and REST (only for Response Processing stage).
The syntaxes are similar to "Header/Query/Path Transformation" section, but only "headers" are supported for the left-hand side.
Method Transformation
In this section, let us see how to do HTTP method transformation (modifying the value of the HTTP Method) using Transformation policy.
Applicable Types: REST
Applicable Stage: Request Processing
This parameter is used to transform the HTTP Method of the request. Supported values are CUSTOM, GET, POST, PUT and DELETE. If CUSTOM is selected, the HTTP method from the incoming request is retained. If any other values are selected, the selected value is set as HTTP Method in the outgoing request to the native service.
Status Transformation
In this section, let us see how to do Status transformation (modifying the value of status code and/or status message) using Transformation policy.
Applicable Types: SOAP/REST
Applicable Stage: Response Processing
This section is used for transforming status code and status message. The child parameters are:
- Code - Status code of the outgoing response. Accepts an integer value, which is set as the status code of the outgoing response to client
- Message - Status message of the outgoing response. Accepts a string value, which is set as the status message of the outgoing response to client
In the above image, the response is set with status 202 CREATED.
Payload Transformation
In this section, let us see how to do payload transformation (modifying the payload using XSLT Transformation) in the Transformation policy.
Accepts one or more XSLT Document or XSLT Transformation alias which contains an XSLT document.
The XSLT documents are used to transform the payload.
Advanced Transformation
This section accepts an webMethods IS Service or webMethods IS Service Alias as input. You can configure an "Invoke IS Service" under a Transformation policy. The "IS Service" can be used to do advanced transformation along with aforementioned transformations. For more details about how to configure webMethods IS Service or webMethods IS Service Alias, refer Usage of “Invoke webMethods IS” policy - 10.2 and later versions.
Transformation Metadata
This section accepts zero or more namespace prefix and namespace URI, which can be used throughout the policy configuration when applying xpath.
For example, define the prefix as "ns" and some value for the URI.
Now, whenever you use ${request.payload.xpath[//ns:emp/ns:empName]} in Transformation Configuration section and/or Condition Section, the URI is applied to the prefix (ns) when applying xpath.
Achieving transformation use cases using Transformation policy
The transformation use cases (1 and 2 in Use cases section) can be achieved by Invoke IS Service as well as using Request Transformation or Response Transformation policy in API Gateway. For more details about the Transformation policies, refer Request and Response Transformation policies in API Gateway.
When to use Transformation policy and when to use Invoke IS Service policy
You can use transformation policies to achieve use cases that can be easily configured in API Gateway UI. However, there may be some use cases that cannot be solved by transformation policies. You can use Invoke IS Service policy to achieve all use cases of transformation, but you need to write an Invoke IS Service to do so, which might take some effort.
Below are some guidelines about when to use these two policies.
-
When you need to do simple transformations that can be configured easily in API Gateway UI, you can use the transformation policy. For example,
-
Add/Modify a header to some constant value (eg: headers.Accept = application/json)
-
Add/Modify a query parameter by reading another content (say reading a header and set it in a query parameter, for example, query.var1 = headers.var1)
-
Remove a header in request or response.
-
Modify the status code/status message/HTTP Method
-
-
Use Invoke IS Service policy to achieve complex use cases of transformation by writing an Invoke IS Service. When you need to write some custom logic (using Java code) to do the transformation, you can use Invoke IS Service policy. Using Java code in IS Service, you can do these complex transformations
-
For transforming the payload using XSLT transformation, use Payload transformation section under the Transformation policy. For payload transformation without XSLT, use Invoke IS Service
-
For executing transformations based on conditions, use conditions in the transformation policy. For example, When status code = 200, execute the transformation configured. Note: You can configure conditions as well as configure Invoke IS Service in Advanced Transformation section of Transformation policy to conditionally invoke an IS Service
Limitations
- The transformation policies (Request Transformation and Response Transformation) supports transformation of payload only using XSL Transformation. If you want to do the payload transformation without using XSL files, by directly setting a value for the payload, you can use the webMethods Invoke IS policy in API Gateway
Downloadable artifacts
The below videos provide a detailed demonstration of Transformation policies in API Gateway. Please find the video files in the attachments.
Learn more
- For more details about the usage of Invoke webMethods IS policy in versions 10.2 and above, refer Invoke webMethods IS policy in API Gateway 10.2