Variable Definition

Overview

Variable is a structure used to extract data from API traffic messages for policy needs. It is used to extract data from different parts of HTTP requests (header, parameter, body, etc.). Variables are used in policies, conditions, and other API configurations to dynamically access request/response data.

Basic Properties

Property	Type	Required	Description
name	string	Yes	Unique name of the variable
description	string	No	Description for the variable
type	EnumVariableType	Yes	Variable type. See Variable Types

Note

• name must be unique within a project

Variable Types

Variables support the following types:

• HEADER - Extract data from HTTP headers
• PARAMETER - Extract data from URL parameters (query, path, form)
• BODY - Extract data from request/response body (XML, JSON, or raw body)
• CONTEXT_VALUES - Extract data from system context values
• CUSTOM - Custom variable defined with script

Variable Types and Required Fields

HEADER Type

Extract data from HTTP headers.

Field	Type	Required	Description
type	string	Yes	Must be HEADER
headerName	string	Yes	Name of the HTTP header field in request or response message

Example

{
  "name": "apiKeyVariable",
  "description": "Extracts API key from header",
  "type": "HEADER",
  "headerName": "X-API-Key"
}

PARAMETER Type

Extract data from URL parameters (query, path, or form).

Field	Type	Required	Description
type	string	Yes	Must be PARAMETER
paramType	string	Yes	Parameter type. See EnumVariableParameterType
paramName	string	Yes	Name of the parameter in request message
paramPath	string	Yes*	Template path to use for "path" parameter (required if paramType=PATH)
formName	string	No	Form field name (optional, used if paramType=FORM and differs from paramName)

Note

• For paramType=QUERY: Use paramName only
• For paramType=PATH: Use paramName and paramPath (required)
• For paramType=FORM: Use paramName (required), formName is optional and typically same as paramName unless you need a different field name

EnumVariableParameterType (paramType)

• QUERY - Query parameter (e.g., ?userId=123)
• PATH - Path parameter (e.g., /users/{userId})
• FORM - Form parameter (form data)

Example 1: Query Parameter

{
  "name": "userIdFromQuery",
  "description": "Extracts user ID from query parameter",
  "type": "PARAMETER",
  "paramType": "QUERY",
  "paramName": "userId"
}

Example 2: Path Parameter

{
  "name": "orderIdFromPath",
  "description": "Extracts order ID from path",
  "type": "PARAMETER",
  "paramType": "PATH",
  "paramName": "orderId",
  "paramPath": "/orders/{orderId}"
}

Example 3: Form Parameter

{
  "name": "usernameFromForm",
  "description": "Extracts username from form data",
  "type": "PARAMETER",
  "paramType": "FORM",
  "paramName": "username",
  "formName": "username"
}

BODY Type

Extract data from request/response body (XML, JSON, or raw body).

Field	Type	Required	Description
type	string	Yes	Must be BODY
messageContentType	string	Yes	Content type. See EnumMessageContentType
xpathValue	string	Yes*	XPath expression for XML body data (required if messageContentType=XML)
jsonPathValue	string	Yes*	JsonPath expression for JSON body data (required if messageContentType=JSON)

EnumMessageContentType (messageContentType)

• XML - XML content type
• JSON - JSON content type
• ALL_BODY - Raw body content (all body)

Example 1: XML Body

{
  "name": "customerNameFromXml",
  "description": "Extracts customer name from XML body",
  "type": "BODY",
  "messageContentType": "XML",
  "xpathValue": "//customer/firstName"
}

Example 2: JSON Body

{
  "name": "emailFromJson",
  "description": "Extracts email address from JSON body",
  "type": "BODY",
  "messageContentType": "JSON",
  "jsonPathValue": "$.user.contact.email"
}

Example 3: All Body

{
  "name": "rawBody",
  "description": "Extracts raw body content",
  "type": "BODY",
  "messageContentType": "ALL_BODY"
}

CONTEXT_VALUES Type

Extract data from system context values.

Field	Type	Required	Description
type	string	Yes	Must be CONTEXT_VALUES
contextValue	string	Yes	Context value type. See EnumVariableContextValue
zoneId	string	Yes*	Time zone ID (required for some context values, e.g., date/time values)

Example

{
  "name": "requestTime",
  "description": "Extracts request time from system context",
  "type": "CONTEXT_VALUES",
  "contextValue": "DATETIME_EPOCH_MILLIS",
  "zoneId": "Europe/Istanbul"
}

CUSTOM Type

Custom variable defined with script.

Field	Type	Required	Default	Description
type	string	Yes	-	Must be CUSTOM
initWithScript	boolean	No	false	Whether to initialize with script (default: false)
scriptLanguage	string	Yes*	-	Script language (required if initWithScript=true). See EnumScriptType
scriptBody	string	Yes*	-	Script body code (required if initWithScript=true)

Note

• If initWithScript is true, both scriptLanguage and scriptBody must be provided
• If initWithScript is false (default), script fields are optional

Example

{
  "name": "customVariable",
  "description": "Custom variable with script",
  "type": "CUSTOM",
  "initWithScript": true,
  "scriptLanguage": "JAVASCRIPT",
  "scriptBody": "return request.header['X-User-ID'];"
}

EnumVariableContextValue

Context values available for CONTEXT_VALUES type variables.

Request-Related Values

Context Value	Description
REQUEST_REMOTE_ADDRESS	Client IP address
REQUEST_HTTP_METHOD	HTTP method (GET, POST, etc.)
REQUEST_CONTENT_TYPE	Request content type
REQUEST_PATH_INFO	Request path information
REQUEST_CONTEXT_PATH	Context path information
REQUEST_QUERY_STRING	URL query string parameters
REQUEST_REMOTE_USER	Remote user information
REQUEST_USERNAME_KEY	Username or key
REQUEST_REQUESTED_SESSION_ID	Session ID
REQUEST_REQUEST_URI	Request URI
REQUEST_CHARACTER_ENCODING	Character encoding
REQUEST_CHARSET	Charset information
REQUEST_CONTENT_LENGTH	Content length
REQUEST_PROTOCOL	Protocol used
REQUEST_SCHEME	Protocol scheme (http, https)
REQUEST_SERVER_NAME	Server name
REQUEST_SERVER_PORT	Server port number
REQUEST_REMOTE_HOST	Remote host information
REQUEST_REMOTE_PORT	Remote port number
REQUEST_LOCAL_NAME	Local server name
REQUEST_LOCAL_ADDR	Local IP address
REQUEST_LOCAL_PORT	Local port number
REQUEST_XFORWARDED_FOR	X-Forwarded-For header value

Request Status Information

Context Value	Description
REQUEST_IS_SOAP_TO_REST	Whether SOAP to REST conversion is active
REQUEST_IS_APIPROXY	API Proxy check
REQUEST_IS_APIPROXYGROUP	API Proxy Group check
REQUEST_IS_XWWW_FORM_URL_ENCODED	Form URL encoded format check
REQUEST_IS_FORM_DATA	Form data format check
REQUEST_IS_BYTE_ARRAY	Byte array format check
REQUEST_HAS_ATTACHMENT	Attachment check
REQUEST_GZIP	GZIP compression status
REQUEST_DEFLATE	DEFLATE compression status
REQUEST_BR	Brotli compression status
REQUEST_ZSTD	Zstandard compression status
REQUEST_IDENTITY	Identity encoding status
REQUEST_COMPRESS	Compress encoding status
REQUEST_HTTP_SERVLET	HTTP Servlet information

Response-Related Values

Context Value	Description
RESPONSE_IS_BYTE_ARRAY	Whether response is in byte array format
RESPONSE_GZIP	GZIP compression status
RESPONSE_DEFLATE	DEFLATE compression status
RESPONSE_BR	Brotli compression status
RESPONSE_ZSTD	Zstandard compression status
RESPONSE_IDENTITY	Identity encoding status
RESPONSE_COMPRESS	Compress encoding status
RESPONSE_STATUS_CODE	HTTP status code
RESPONSE_HTTP_SERVLET	HTTP Servlet information

Message-Related Values

Context Value	Description
MESSAGE_CORRELATION_ID	Message correlation ID

Environment-Related Values

Context Value	Description
ENVIRONMENT_ID	Environment ID
ENVIRONMENT_NAME	Environment name
ENVIRONMENT_CERTIFICATE	Certificate map
ENVIRONMENT_PRIVATEKEY	Private key map
ENVIRONMENT_PUBLICKEY	Public key map
ENVIRONMENT_SECRETKEY	Secret key map
ENVIRONMENT_KEYSTORE	Keystore map
ENVIRONMENT_JWK	JWK map

API Proxy Group/Proxy/Method Values

Context Value	Description
APIPROXYGROUP_ID	API Proxy Group ID
APIPROXYGROUP_NAME	API Proxy Group name
APIPROXY_ID	API Proxy ID
APIPROXY_NAME	API Proxy name
APIMETHOD_ID	API Method ID
APIMETHOD_NAME	API Method name
APIMETHOD_SOAP_ACTION	SOAP action value
APIMETHOD_HTTPMETHOD	HTTP method
APIMETHOD_ENDPOINT	Endpoint information
APIMETHOD_BACKEND_HTTPMETHOD	Backend HTTP method
APIMETHOD_BACKEND_ENDPOINT	Backend endpoint information

Date/Time-Related Values

Context Value	Description	zoneId Required
DATETIME_YEAR	Year	Yes
DATETIME_MONTH	Month	Yes
DATETIME_DAY_OF_WEEK	Day of week	Yes
DATETIME_DAY_OF_MONTH	Day of month	Yes
DATETIME_HOUR	Hour	Yes
DATETIME_MINUTE	Minute	Yes
DATETIME_SECOND	Second	Yes
DATETIME_EPOCH_MILLIS	Epoch milliseconds	Yes
DATETIME_FORMATTED_TEXT	Formatted date-time	Yes
DATE_FORMATTED_TEXT	Formatted date	Yes
TIME_FORMATTED_TEXT	Formatted time	Yes

Note: Date/time context values require zoneId field to be specified.

Credential Values

Context Value	Description
CREDENTIAL_USERNAME	Username
CREDENTIAL_EMAIL	Email address
CREDENTIAL_FULLNAME	Full name
CREDENTIAL_SECRETKEY	Secret key
CREDENTIAL_CERTIFICATE	Certificate
CREDENTIAL_PUBLICKEY	Public key
CREDENTIAL_PRIVATEKEY	Private key
CREDENTIAL_KEYSTORE	Keystore
CREDENTIAL_TRUSTSTORE	Truststore
CREDENTIAL_JWK_SIGNANDVALIDATION	JWK for signing and validation
CREDENTIAL_JWK_ENCRYPTIONANDDECRYPTION	JWK for encryption and decryption

Complete Variable Examples

Example 1: Header Variable

{
  "name": "apiKeyVariable",
  "description": "Extracts API key from header",
  "type": "HEADER",
  "headerName": "X-API-Key"
}

Example 2: Query Parameter Variable

{
  "name": "userIdFromQuery",
  "description": "Extracts user ID from query parameter",
  "type": "PARAMETER",
  "paramType": "QUERY",
  "paramName": "userId"
}

Example 3: Path Parameter Variable

{
  "name": "orderIdFromPath",
  "description": "Extracts order ID from path",
  "type": "PARAMETER",
  "paramType": "PATH",
  "paramName": "orderId",
  "paramPath": "/orders/{orderId}"
}

Example 4: XML Body Variable

{
  "name": "customerNameFromXml",
  "description": "Extracts customer name from XML body",
  "type": "BODY",
  "messageContentType": "XML",
  "xpathValue": "//customer/firstName"
}

Example 5: JSON Body Variable

{
  "name": "emailFromJson",
  "description": "Extracts email address from JSON body",
  "type": "BODY",
  "messageContentType": "JSON",
  "jsonPathValue": "$.user.contact.email"
}

Example 6: Context Variable (Client IP)

{
  "name": "clientIp",
  "description": "Extracts client IP address",
  "type": "CONTEXT_VALUES",
  "contextValue": "REQUEST_REMOTE_ADDRESS"
}

Example 7: Context Variable (Date/Time)

{
  "name": "requestTime",
  "description": "Extracts request time",
  "type": "CONTEXT_VALUES",
  "contextValue": "DATETIME_EPOCH_MILLIS",
  "zoneId": "Europe/Istanbul"
}

Example 8: Custom Variable

{
  "name": "customUserId",
  "description": "Custom variable to extract user ID",
  "type": "CUSTOM",
  "initWithScript": true,
  "scriptLanguage": "JAVASCRIPT",
  "scriptBody": "var header = request.header['X-User-ID']; return header ? header : request.header['Authorization'].split(' ')[1];"
}

Usage in Policies

Variables are used in various policies:

• API Based Throttling - targetVariableForIdentity to identify clients
• RLCL - targetVariable for rate limiting
• Conditions - firstVariable and secondVariable for condition rules
• Content Filter - Variables to filter content
• Redaction - Variables to identify data to redact
• Encryption/Decryption - Variables for source and target data

Notes and Warnings

• Variable Names:

  • Variable names must be unique within a project
  • Use descriptive names for better understanding

• Required Fields:

  • Each variable type has specific required fields
  • Missing required fields will cause validation errors

• Context Values:

  • Date/time context values require zoneId field
  • Use IANA time zone identifiers (e.g., "Europe/Istanbul", "America/New_York")

• XPath/JsonPath:

  • XPath expressions are used for XML content
  • JsonPath expressions are used for JSON content
  • Ensure expressions are valid for the content type

• Custom Scripts:

  • Custom variables use scripts to extract data
  • Script language must be specified
  • Scripts have access to request/response objects

Related Documentation

• Enum Reference - Enumeration values used in variables (EnumVariableType, EnumVariableParameterType, etc.)
• Glossary - Terms and definitions
• API Based Throttling Policy - Uses variables for client identification
• RLCL API - Uses variables for rate limit control
• Script Policy - Script language types