Software AG Products 10.5 | Using API Gateway | Policies | System-defined Stages and Policies | Request Processing | Request Transformation
 
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.
API Gateway supports the following parameter types that can be used to configure the transformation policy:
*List of variables supported for all API Types
request.headers.HEADER_NAME
request.authorization.apiKey
request.authorization.clientId
request.authorization.claims.CLAIM_NAME
request.authorization.userName
request.authorization.issuer
request.authorization.authHeader
request.authorization.incomingToken
request.authorization.audience
request.correlationID
request.application.id
request.application.name
request.application.version
request.application.claims.claimName
Note: 
*The request.authorization.claims.CLAIM_NAME and request.application.claims.claimNames request transformation variables must be used for JWT authorized APIs.
*The request.authorization variables are retrieved from token introspection and not from the scope that you have defined in the external authorization server. The request authorization variable values are retrieved from the incoming JWT tokens when the introspection is done locally and the values are retrieved from the remote introspection response received from the authorization server when the introspection is done remotely.
*List of variables supported only for REST APIs
request.query.QUERY_NAME
request.path
request.path.regex[Expression]
request.path.PATH_PARAM_NAME
request.httpMethod
jms.query.QUERY_NAME
jms.path
jms.httpMethod
jms.path.regex[Expression]
jms.headers.HEADER_NAME
The parameter types that are of the format jms.xxx are used when you want to use JMS/AMQP so that transformation can be applied for the jms/amqp values
API Gateway supports the following Query types that can be applied on payload to extract values from payload:
*xpath
*jsonPath
*regex
When you use these syntaxes to extract a value from the payload, the content-types applicable are:
*${request.payload.jsonPath[Expression]} - application/json, application/json/badgerfish
*${request.payload.regex[Expression]} - text/plain
*${request.payload.xpath[Expression]} - application/xml, text/xml, text/html. This is to be used to extract values when APIs with Transformation policy are JWT authorized.
The table lists the properties that you can specify for this policy:
Parameter
Description
Condition
Conditions are used to specify when the policy has to be executed. You can add multiple conditions with logical operators.
Available values are:
*AND. API Gateway transforms the requests that comply with all the configured conditions.
*OR. This is selected by default. API Gateway transforms the requests that comply with at least one configured condition.
Click Add Condition and provide the following information and click .
*Variable: Specifies the variable type with a syntax as follows:
*${PARAMTYPE} : This is applicable for variables of string type - path, payload, httpMethod. For example: ${request.path}
*${PARAMTYPE.paramName} : This is applicable for map types - query and headers and also applicable for path. For example: ${request.query.var1}, ${request.header.Content-Type}, ${request.path.name}
*${PARAMTYPE.QUERYTYPE[queryValue]} : This syntax is applicable for payload and path. regex can be applied on path while XPath, JSONPath and regex can be applied on payload. For 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
${request.payload.jsonPath[$.cardDetails.number]} where $.cardDetails.number is the jsonPath to be applied on the payload if contentType is application/json
${request.payload.regex[[0-9]+]} where [0-9]+ is the regex to be applied on the payload if contentType is text/plain
*If you want API Gateway to apply xpath, jsonPath, regex based on Content-Type of the payload, use the following common syntax: ${PARAMTYPE.QUERYTYPE[queryValue] || PARAMTYPE.QUERYTYPE2[queryValue2] || ...}
For example:
${request.payload.xpath[//ns:emp/ns:empName] || request.payload.jsonPath[$.cardDetails.number]} This 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 applies xpath for application/xml, jsonPath for application/json, and regex for text/plain.
*Operator: Specifies the operator to use to relate variable and the value provided. You can select one of the following:
*Equals
*Equals ignore case
*Not equals
*Contains
*Exists
*Value: Specifies a value with a syntax as follows:
*PLAIN VALUE, for example, application/json
*${PARAMTYPE.paramName}
*${PARAMTYPE.QUERYTYPE[queryValue]}
*${PARAMTYPE.QUERYTYPE[queryValue] || PARAMTYPE.QUERYTYPE2[queryValue2] || ...}
Transformation Configuration: Specifies various transformations to be configured.
Header/Query/Path Transformation for REST API
and
Header Transformation for SOAP API
Specifies the Header, Query or path transformation to be configured for incoming requests.
You can add or modify header, query or path transformation parameters by providing the following information:
*Variable. Specifies the variable type with a syntax as follows:
*${PARAMTYPE}. This is applicable for variables of string type - path, payload, httpMethod. For example: ${request.path}
*${PARAMTYPE.paramName}. This is applicable for map types - query and headers and also applicable for path. For example: ${request.query.var1}, ${request.header.Content-Type}, ${request.path.name}
*${PARAMTYPE.QUERYTYPE[queryValue]}. This syntax is applicable for payload and path. regex can be applied on path while XPath, JSONPath and regex can be applied on payload. For 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
${request.payload.jsonPath[$.cardDetails.number]} where $.cardDetails.number is the jsonPath to be applied on the payload if contentType is application/xml
${request.payload.regex[[0-9]+]} where [0-9]+ is the regex to be applied on the payload if contentType is anything
*If you want API Gateway to apply xpath, jsonPath, regex based on Content-Type of the payload, use the following common syntax: ${PARAMTYPE.QUERYTYPE[queryValue] || PARAMTYPE.QUERYTYPE2[queryValue2] || ...}
For example:
${request.payload.xpath[//ns:emp/ns:empName] || request.payload.jsonPath[$.cardDetails.number]} This 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 applies xpath for application/xml, jsonPath for application/json, and regex for text/xml.
Note:
The parameter types that are of the format jms.xxx are used when you want to use JMS/AMQP so that transformation can be applied for the jms/amqp values. For example, if you have set the path parameter as jms.path.petid and the corresponding value as jms.header.h1, then if the request contains the header value h1, the value h1 is replaced by the path parameter petid.
*Value. Specifies a value with a syntax as follows:
*PLAIN VALUE, for example, application/json
*${PARAMTYPE.paramName}
*${PARAMTYPE.QUERYTYPE[queryValue]}
*${PARAMTYPE.QUERYTYPE[queryValue] || PARAMTYPE.QUERYTYPE2[queryValue2] || ...}
You can add multiple variables and corresponding values by clicking .
You can remove any header, query or path transformation parameters by typing the value in the text box.
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.
Note:
Payload transformation does not happen automatically for content-type transformation. When you change the content type, ensure to do payload transformation also as part of IS Service. For example, if you change the content-type header from application/xml to application/json using IS service, you must also change the respective payload from application/xml to application/json.
Method transformation for REST API
Specifies the method transformation to be configured for incoming requests.
Select any of the HTTP Method listed:
*GET
*POST
*PUT
*DELETE
*HEAD
*CUSTOM
Note:
When CUSTOM is selected, the HTTP method in incoming request is sent to the native service. When other methods are selected, the selected method is used in the request sent to the native service.
Note:
Only Method Transformation happens when configured, but you have to take care of adding payload during transformations involving method change like GET to POST, and so on.
Payload Transformation
Specifies the payload transformation to be configured for incoming requests.
Provide the following information:
*Click + Add xslt document to add an xslt document and provide the following information:
*XSLT file. Specifies the XSLT file used to transform the request messages as required.
Click Browse to browse and select a file.
*Feature Name. Specifies the name of the XSLT feature.
*Feature value. Specifies the value of the XSLT feature.
You can add more XSLT features and xslt documents by clicking .
Note:
API Gateway supports XSLT 1.0 and XSLT 2.0.
*Click + Add xslt transformation alias and provide the following information:
*XSLT Transformation alias. Specifies the XSLT transformation alias
When the incoming request is in JSON, you can use a XSLT file similar to the below sample:
<?xml version="1.0" ?>
<xsl:stylesheet version="1.1"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:output method="xml"/>

<xsl:template match="/" >
<xsl:element name="fakeroot">
<xsl:element name="fakenode">
<!-- Apply your transformation rules based on the request from the Client-->
</xsl:element>
</xsl:element>
</xsl:template>
</xsl:stylesheet>
When the incoming request is in XML, you can use a XSLT file similar to the below sample:
<?xml version="1.0" ?>
<xsl:stylesheet version="1.1"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">

<xsl:output method="xml"/>

<xsl:template match="/" >
<xsl:element name="soapenv:Envelope">
<xsl:element name="soapenv:Body">
<!-- Apply your transformation rules based on the request from the Client-->
</xsl:element>
</xsl:element>
</xsl:template>
</xsl:stylesheet>
Advanced Transformation
Specifies the advanced transformation to be configured for incoming requests.
Provide the following information:
*webMethods IS Service. Specify the webMethods IS service to be invoked to process the request messages.
You can add multiple services by clicking .
Note:
The webMethods IS service must be running on the same Integration Server as API Gateway.
*Run as User. Specifies the authentication mode to invoke the IS service. If this field is left blank the incoming credentials of the user, identified by API Gateway, are used to authenticate and invoke the IS service. You can also specify a particular user, you want API Gateway to use to invoke the IS service.
*Comply to IS Spec. Mark this as true if you want the input and the output parameters to comply to the IS Spec present in pub.apigateway.invokeISService.specifications folder in wmAPIGateway package.
*webMethods IS Service alias. Specifies the webMethods IS service alias to be invoked to pre-process the request messages.
Transformation Metadata: Specifies the metadata for transformation of the incoming requests. For example, the namespaces configured in this section can be used when you provide the syntax for XPath ${request.payload.xpath} For example: ${request.payload.xpath[//ns:emp/ns:empName]}
Namespace
Specifies the namespace information to be configured for transformation.
Provide the following information:
*Namespace Prefix. The namespace prefix of the payload expression to be validated.
*Namespace URI. The namespace URI of the payload expression to be validated.
Note:
You can add multiple namespace prefix and URI by clicking .