API Gateway 10.7 | Using API Gateway | Policies | System-defined Stages and Policies | Variable Framework
 
Variable Framework
All types of variables such as request, response, custom, custom-context, and system context variables are handled through the common framework called variable framework. The variable framework in API Gateway provides an option to extract variable values that can be used across stages. For example, you can use the extracted variable to transform request and response contents such as headers, query parameters, path parameters payload, and so on as per your requirement. With the variable framework, you can normalize the syntax and create a common template for accessing the various variable types.
The following table summarizes the keywords that are used to define the variable syntaxes:
Variable keyword
Description
paramStage
Defines the stage of the system defined policy. Possible values are:
*request
*response
paramType
Defines the specific parameter of the request or response. Possible values are:
*payload
*headers
*query
*path
*httpMethod
*statusCode
*statusMessage
queryType
Defines the query that can be applied over string elements like payload. Possible values are:
*xpath
*jsonPath
*regex
The following variable types are available in the request or response stages:
*${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.
Note:
While 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.
Provide the following variable, if there is a blank space in the parameter name ${request.payload.jsonPath[$.['param name'] ]}
For example, if the parameter name is first name, then provide the variable as ${request.payload.jsonPath[$.['first name']]}.
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.
Note:
If the authorization header has bearer tokens ( such as OAuth, OpenID, or JWT), then you cannot use this
variable. In such cases, Software AG recommends to use the ${request.authorization.incomingToken} variable.
${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.exp }
Gets the value for the claim name from the claims identified from the Authorization header by the configured IAM policy. This format is applicable when a JWT token is used for authorization.
${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. This format is applicable when a JWT token is used for authorization.
${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]}
Example:${request.application.payloadIdentifier[1]}
Gets the value of the payload identifier in the specified index for the application identified for this request.
${request.application.team[NUMBER]}
Example: ${request.application.team[0]}
Gets the value of the team identifier in the specified index for the application identified for this request.
${request.application.token[NUMBER]}
Example:${request.application.token[1]}
Gets the value of the token identifier in the specified index for the application identified for this request.
${request.application.username[NUMBER]}
Example:${request.application.username[0]}
Gets the value of the username identifier in the specified index for the application identified for this request.
${request.application.wssUsername[NUMBER]}
Example:${request.application.wssUsername[0]}
Gets the value of the wssUsername identifier in the specified index for the application identified for this request.
${request.application.headers.HEADER_NAME}
Example:${request.application.headers.Accept}
Gets the value of the header name for the headers identifier configured in the application identified for this request.
Response variables
Variables that allow you to extract and reuse values in the response processing stage.
Variable Syntax
Description
${response.headers.NAME}
Example: ${response.headers.Accept}
Gets the value of the header name in the response.
${response.statusCode}
Gets the value for the status code for the response.
${response.statusMessage}
Gets the value for the status message in the response
${response.payload.xpath[EXPR]}
Example:${response.payload.xpath[//ns:emp/ns:empName]} where //ns:emp/ns:empName is the xpath to be applied on the payload if contentType is application/xml
Gets the value of the payload from the specified xpath of the response.
Note:
The namespace URI for the prefixes you have configured in the xpath expression are resolved using namespaces configured in the metadata section in the policy or using the namespaces configured through XpathNamespaces custom variable in the custom extension policy.
${response.payload.jsonPath[EXPR]}
Example:${response.payload.jsonPath[$.cardDetails.number]} where $.cardDetails.number is the jsonPath to be applied on the payload if contentType is application/json
Gets the value of the payload from the specified jsonPath of the response.
${response.payload.regex[EXPR]}
Example: ${ response.payload.regex[[0-9]+]} where [0-9]+ is the regex to be applied on the payload if contentType is text/plain
Gets the value of the payload from the specified regex of the response.
API Gateway evaluates and supports the array expressions in JSON path.
Example: Consider the following payload.

{
"firstName":"John",
"lastName":"doe",
"age":26,
"address":
{"streetAddress":"naist street","city":"Nara","postalCode":"630-0192"}
,
"phoneNumbers":[
{"type":"iPhone","number":"0123-4567-8888"}
,
{"type":"home","number":"0123-4567-8910"}
]
}
Following are the responses for the expressions after evaluating the array expressions in JSON path.
Expressions
Response
$.phoneNumbers[1].type
"home"
$.phoneNumbers[0,1].type or $.phoneNumbers[:2].type
["iPhone","home"]
$.phoneNumbers[0,1] or $.phoneNumbers[:2]
[{"type":"iPhone","number":"0123-4567-8888"} \{"type":"home","number":"0123-4567-8910"}]
$..firstName
["John"]
$.firstName
"John"
$.address.city
"Nara"
System Context Variables
API Gateway provides predefined system context variables and the values of these variables are extracted from the client request.
Variable Syntax
Description
${apiId}
Get the value of the API ID.
${apiName}
Get the name of the API.
${apiVersion}
Get the version of the API.
${packageId}
Get the value of the package ID.
${planId}
Get the value of the plan ID.
${customTransactionFields.FIELD_NAME}
Example: ${customTransactionFields.sample}
Provides you an option to get or set custom fields to the transactional events for this request. To set the custom fields, you can configure the customTransactionFields.FIELD_NAME custom variable in Custom Extension policy.
${providerTime}
Gets the time taken in milliseconds between the request sent to native server and response received from native server for this transaction.
${date}
Gets the date when the request gets invoked.
${dynamicEndpoint}
Gets the value of the ROUTING_ENDPOINT context variable set using pub.apigateway.ctxvar:setContextVariable.
${time}
Gets the time when the request gets invoked.
${user}
Gets the value of the user ID who sends the request.
${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://host:port/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://host:port/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.
${gatewayHostname}
Example: uk.myhost.com
Gets the API Gateway host name.
${gatewayIP}
Example: 198.168.1.9
Gets API Gateway IP address.
${operationName}
Example: addInts
Gets the value of API operation selected from the request. Operation names are available only for SOAP APIs. It is empty for REST API.
${nativeEndpoint}
Example: http://host:port/Service
Gets the value of the native endpoints from the request. It returns value only after executing the routing policy.
In addition, the variable framework also supports the following variables:
*${jms.headers.NAME}
*${jms.query.NAME}
*${jms.path}
*${jms.path.regex[EXPR]}
*${jms.httpMethod}
*${jms.payload.xpath[EXPR]}
*${jms.payload.jsonPath[EXPR]}
*${jms.payload.regex[EXPR]}
*${jms.statusCode}
Note:
You can use these variables when you want to use JMS/AMQP so that transformation can be applied for the JMS/AMQP values. For example, if you set the path parameter as jms.path.petidand 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.
Enhancements to Variable Framework Support
Until API Gateway version 10.5, the variable framework was supported in API Mashup, Request Transformation, Response Transformation, Conditional Error Processing, and Custom Extension policies.
In API Gateway version 10.7 the existing variable framework is enhanced to support the following use cases:
*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.
Note:
As like the earlier versions of API Gateway, you can also define and access the custom-context variable or custom-variable using the ctxVar IS Service. For details, see The API for Context Variables.
*Both system context variables and custom variables (that includes custom context variables) are accessible across all policy parameters that support variables.