The API Platform defines a set of variables that can be populated at runtime to obtain detailed information about the events that occur during a transaction executed by an API proxy. Variables are the primary source of information used to enable conditional execution of flows, policies, and routes. 

In a simple example, a condition could be configured to check the value of the system.time variable, enabling a policy to be enforced only between the hours of 9-5. More sophisticated examples use the value of variables that represent events in the API proxy flow, such as policy failures or code execution, to branch the processing Flow. Variables are also commonly used to execute policies based on the URI path and HTTP verb associated with request messages.  

Predefined variables are categorized based on functionality. These variables have a well-defined data type. All variables follow a "dotted" naming convention (components separated by periods, e.g., system.time.hour) and each segment in the variable name indicates the scope of the variable. All variable names are lower case. 

The scope field in the table below indicates the Flow during the variable is available. Most variables are available throughout the end-to-end Flow, though some are scoped specifically to the ProxyEndpoint request or response, or the TargetEndpoint request or response. Some variables are only available during the default ErrorFlow.

See Use variables to control flow logic for more information about variable types.

For OAuth-related variables (developer, access token, apiproduct, etc.), see OAuth flow variables.

System variables

System variables contain system-related information. A system variable is prefixed with _system. wherever it is referenced. The part of the variable that appears after the prefix specifies the function in the system, such as host name, date, time, and interfaces. The supported system variables are listed below.

System variable Scope Type Permission Description 
system.timestamp Always Date Read Timestamp of the system
system.time Always String Read Time captured by the system
system.time.year Always Integer Read Year captured by the system
system.time.month Always Integer Read Month captured by the system
system.time.day Always Integer Read Day of the month captured by the system
system.time.dayofweek Always Integer Read Day of the week captured by the system
system.time.hour Always Integer Read Hour of the morning or afternoon captured by the system
system.time.minute Always Integer Read Minute within the hour captured by the system
system.time.second Always Integer Read Second within the minute captured by the sytem
system.time.millisecond Always Integer Read Millisecond within the second captured by the system
system.time.zone Always String Read Timezone of the system
system.time.host Always String Read Host name of the system
system.interface.{interface_name} Always String Read IP Address of the system

Configuration variables

Configuration variables represent the configuration settings for an organization on the API Platform. The supported configuration variables are listed below.

Configuration variables Scope Type Permission Description
organization.name Always String Read Name of the organization
environment.name Always String Read Name of the environment
apiproxy.name Always String Read Name of the apiproxy
apiproxy.revision Always String Read Revision no of apiproxy
is.error Always Boolean Read Error flag
proxy.basepath Always Boolean Read The base path (URI) configured for the ProxyEndpoint
proxy.name Always String Read The name attribute configured for the ProxyEndpoint
proxy.pathsuffix Always String Read The request URI path fragment following the URI base path URI fragment

Message variables

Message variables are contextual objects, and are the same as requests during the request Flow, responses during the response Flow, or errors during the error Flow. The supported message variables are listed below.

Message variables Scope Type Permission Description 
error Error Message Read/Write Error of type Message which is a contextual object in the error flow
error.content Error String Read/Write Content of the error 
error.message Error String Read Message associated with an error, whose value is available only before the error Flow is executed
error.transport.message Error Transport_Message Read Any error of type TransportMessage 
error.state Error Integer Read State in the Flow where an error occured
message Always Message Read/Write A contextual object, with the same value as request in the request Flow or as response in the response Flow or as error in the Error flow.
message.content Always String Read/Write Content of the request or response message
message.formparam.{formparam_name} Always String Read/Write Value of the specified form parameter
message.formparam.{formparam_name}.values Always Collection Read All values of the specified form parameter in the message
message.formparam.{formparam_name}.values.count Always Integer Read Count of the values of the specified form parameters in the message
message.formparams.count Always Integer Read Count of all form parameters in the message
message.formparams.names Always Collection Read Value of all form parameters in the message
message.formstring Always String Read Value of form string in the message
message.header.{header_name} Always String Read Value of the specified HTTP header in the message
message.header.{header_name}.values Always Collection Read All values of the specified HTTP header name in the message
message.header.{header_name}.values.count Always Integer Read Count of the values of the specified HTTP header name in the message
message.headers.count Always Integer Read Count of all HTTP headers in the message
message.headers.names Always Integer Read Value of all HTTP headers in the message
messagelogging.{policy-name}.failed Always Boolean Read Failure flag for the mentioned Message logging policy (not supported in Apigee Enterprise Cloud)
messagelogging.failed Always Boolean Read Failure flag for Message logging policy (not supported in Apigee Enterprise Cloud)
message.queryparam.{queryparam_name}.values Always Integer Read Value of the specified query parameter in the message
message.transport.message Always Transport_Message Read Message of type TransportMessage which is a contexual object 

Policy variables

Policy variables are created as a result of policy executions, and are in the format <PolicyType>.<PolicyName>.<VariableName>

Note: <PolicyType>.<PolicyName>.failed and <PolicyType>.failed variables return true if the policy execution fails. The value is null/false when a policy executes successfully. The supported policy variables are listed below.

Configuration variables Scope Type Permission Description
acl.{policy-name}.failed Always Boolean Read Returns true if the particular acl policy execution results in failure, else false or NULL
acl.failed Always Boolean Read Returns true if acl policy execution results in failure, else false or NULL
assignmessage.{policy-name}.failed Always Boolean Read Returns true if the particular assign message policy execution results in failure, else false or NULL
assignmessage.failed Always Boolean Read Returns true if assign message policy execution results in failure, else false or NULL
extractvariables.{policy-name}.failed Always Boolean Read Returns true if the particular extract variable policy execution results in failure, else false or NULL
extractvariables.failed Always Boolean Read Returns true if extract variable policy execution results in failure, else false or NULL
is.error Always Boolean Read Returns true only if a policy execution fails, else false or NULL
invalidatecache.{policy-name}.failed Always Boolean Read Returns true if the particular invalidate cache policy execution results in failure, else false or NULL
invalidatecache.failed Always Boolean Read Returns true if invalidate cache policy execution results in failure, else false or NULL
javacallout.{policy-name}.failed Always Boolean Read Returns true if the particular java callout policy execution results in failure, else false or NULL
javacallout.failed Always Boolean Read Returns true if java callout policy execution results in failure, else false or NULL
lookupcache.{policy-name}.assignto Always Boolean Read Variable that contains all the cache content of the particular policy
lookupcache.{policy-name}.cachehit Always Boolean Read Flag whether the cache is read from or not for the particular policy
lookupcache.{policy-name}.cachekey Always String Read Key based on which the cache is read  for the particular policy
lookupcache.{policy-name}.cachename Always String Read Name of the cache read  for the particular policy
lookupcache.{policy-name}.failed Always Boolean Read Returns true if the particular lookup cache policy execution results in failure, else false or NULL
lookupcache.failed Always Boolean Read Returns true if lookup cache policy execution results in failure, else false or NULL
populatecache.{policy-name}.failed Always Boolean Read Returns true if the particular populate cache policy execution results in failure, else false or NULL
populatecache.failed Always Boolean Read Returns true if populate cache policy execution results in failure, else false or NULL
ratelimit.{policy-name}.allowed.count Always Long Read Defined quota, after which alarms are raised for a given Rate Limit policy
ratelimit.{policy-name}.available.count Always Long Read Available quota in the current time window (Defined quota - Used quota) for a given Rate Limit policy
ratelimit.{policy-name}.class Always String Read A key or refernce, based on which a separate bucket can be added for different values of the key. Example - Have a bucket per class based on clientId from request header - If the clientId is A, then the bucket is 100, if clientId is B then the bucket is 20. 
ratelimit.{policy-name}.class.allowed.count Always Long Read For a given class, the allowed quota in the current time window for a given Rate Limit policy
ratelimit.{policy-name}.class.available.count Always Long Read For a given class, the available quota in the current time window for a given Rate Limit policy
ratelimit.{policy-name}.class.exceed.count Always Long Read For a given class, the quota exceeded in the current time window for a given Rate Limit policy
ratelimit.{policy-name}.class.total.exceed.count Always Long Read For a given class, the total quota exceeded across all time windows for a given Rate Limit policy
ratelimit.{policy-name}.class.used.count Always Long Read For a given class, the used quota in the current time window for a given Rate Limit policy
ratelimit.{policy-name}.exceed.count Always Long Read Exceeded quota in the current time window for a given Rate Limit policy
ratelimit.{policy-name}.expiry.time Always Long Read Time in milliseconds in which a new quota time window starts for a given Rate Limit policy 
ratelimit.{policy-name}.failed Always Boolean Read Returns true if the particular rate limit policy execution results in failure, else false or NULL
ratelimit.{policy-name}.identifier Always String Read An identifier or key, based on which a separate bucket can be added. Example - Have a bucket per identifier based on clientId from request header
ratelimit.{policy-name}.total.exceed.count Always Long Read The total exceeded quota across all time windows since the given Rate Limit policy was implemented
ratelimit.{policy-name}.used.count Always Long Read Used quota in the current time window (Defined quota - Available quota) for a given Rate limit policy
ratelimit.failed Always Boolean Read Returns true if rate limit policy execution results in failure, else false or NULL
request.formparam.{formparam_name}.values Always Collection Read All the values of a particular form parameter in a request
request.queryparam.{queryparam_name}.values Always Collection Read All the values of a particular query parameter in a request
responsecache.{policy-name}.cachehit Always Boolean Read Flag whether the cache is hit or not
responsecache.{policy-name}.cachekey Always String Read The key, based on which the cache is hit for a given Response Cache policy (Prefix_KeyFragemnt)
responsecache.{policy-name}.cachename Always String Read Name of the cache used for a given Response cache policy
responsecache.{policy-name}.failed Always Boolean Read Returns true if the particular response cache policy execution results in failure, else false or NULL
responsecache.{policy-name}.invalidentry Always Boolean Read Returns true if the cache entry is invalid, else false
responsecache.failed Always Boolean Read Returns true if response cache policy execution results in failure, else false or NULL
response.formparam.{formparam_name}.values Always Collection Read All the values of a particular form parameter in the response
script.{policy-name}.failed Always Boolean Read Returns true if the particular script policy execution results in failure, else false or NULL
script.failed Always Boolean Read Returns true if script policy execution results in failure, else false or NULL
servicecallout.{policy-name}.failed Always Boolean Read Returns true if the particular service callout policy execution results in failure, else false or NULL
servicecallout.failed Always Boolean Read Returns true if service callout policy execution results in failure, else false or NULL
xsl.{policy-name}.failed Always Boolean Read Returns true if the particular XSL policy execution results in failure, else false or NULL
xsl.failed Always Boolean Read Returns true if XSL policy execution results in failure, else false or NULL

Request message variables

Request message variables include components such as header, query param, form param, source IP, and XPath. Request messages are received by proxy and the same request is sent to the target. The supported request message variables are listed below.

Request message variables Scope Type Permission Description
client.cn Proxy request String Read Common name in the SSL certificate presented by the client
client.country Proxy request String Read Country in the SSL certificate presented by the client
client.email.address Proxy request String Read Email address in the SSL certificate presented by the client
client.host Proxy request String Read Originating client host of the request received by the ProxyEndpoint
client.ip Proxy request String Read Originating IP address of the request received by the ProxyEndpoint
client.organization Proxy request String Read Organization in the SSL certificate presented by the client. (Not necessarily equivalent to organization on Apigee Enterprise.)
client.organization.unit Proxy request String Read Organizational unit in the SSL certificate presented by the client.
client.locality Proxy request String Read Locality (City) in the SSL certificate presented by the client.
client.port Proxy request Integer Read HTTP port of the originating client request to ProxyEndpoint 
client.received.end.time Proxy request String Read Ending time at which request is received from originating client at ProxyEndpoint
client.received.end.timestamp Proxy request Long Read Ending timestamp at which request is received from originating client at ProxyEndpoint
client.received.start.time Proxy request String Read Starting timestamp at which request is received from source at ProxyEndpoint
client.received.start.timestamp Proxy request Long Read Starting timestamp at which request is received from source at ProxyEndpoint
client.state Proxy request String Read State in the SSL certificate presented by the client.
client.scheme Proxy request String Read Returns http or https depending on the transport used by client to send the request message
client.ssl.enabled Proxy request Boolean Read Returns true or false, depending on whether the ProxyEndpoint is configured for SSL
keyvaluemapoperations (policy name) - {key} Proxy request String Read Return true/false for the keys in the keyvaluemap <PUT> operation. Indicates whether the put action for the key on the map is success/failure
message.path Proxy request String Read/Write Complete message path in url excluding queryparam.For example : if ProxyEndpoint defined is /123 & message sent is /123/456/test then message.path will return /123/456/test
message.queryparam.{queryparam_name} Proxy request String Read Returns the specific message query parameter
message.queryparam.{queryparam_name}.values.count Proxy request Integer Read Total no of specific queryparam(say queryparam_name) present in the message
message.queryparams.count Proxy request Integer Read Total no of queryparams coming in message
message.queryparams.names Proxy request Collection Read All queryparam name present in the message
message.querystring Proxy request String Read Complete queryparam in message.For example : if the request is http://host.com/123?name=first&surname=second&place=address then this variable will return name=first&surname=second&place=address
message.uri Proxy request String Read Returns complete URI  including query parameters, for example, 123?name=first&surname=second&place=address
message.verb Proxy request String Read Returns HTTP verb (GET, PUT, POST, DELETE, etc.) of the originating client request
message.version Proxy request String Read/Write Returns http version
proxy.basepath Proxy request String Read/Write Return basepath configured in proxyendpoint
proxy.client.ip Proxy request String Read Client ip from where proxy is hit
proxy.pathsuffix Proxy request String Read The URI path fragment appended to the URI base path defined in the ProxyEndpoint
proxy.url Proxy request String Read/Write Returns complete URL oforginating client request to the ProxyEndpoint, including any query parameters present
request Proxy request Message Read The complete request, including any payload present.
request.content Proxy request String Read/Write Returns only the payload of the request
request.formparam.{formparam_name} Proxy request String Read/Write The value of a particular form parameter in the request
request.formparam.{formparam_name}.values.count Proxy request Integer Read Count of all values of  a particular form parameter in the request
request.formparams.count Proxy request Integer Read Count of all the form parameters in the request
request.formparams.names Proxy request Collection Read Name of all the form parameters in the request
request.formstring Proxy request String Read Complete formparam in request. Example: name=test&type=first&group=A
request.header.{header_name} Proxy request String Read/Write The value of a particular header found in the request
request.header.{header_name}.values Proxy request Collection Read All the values of a particular header in the request
request.header.{header_name}.values.count Proxy request Integer Read Count of all the values of a particular header in the request
request.headers.count Proxy request Integer Read Count of all the headers in the request
request.headers.names Proxy request Collection Read Names of all the headers in the request
request.path Proxy request String Read/Write Complete request path in url excluding queryparam.For example : if ProxyEndpoint defined is /123 & message sent is /123/456/test then message.path will return /123/456/test
request.queryparam.{queryparam_name} Proxy request String Read/Write The value of a particular query parameter found in the request
request.queryparam.{queryparam_name}.values.count Proxy request Integer Read Count of all the values of a particular query parameter in the request
request.queryparams.count Proxy request Integer Read Count of all the query parameters in the request
request.queryparams.names Proxy request Collection Read Names of all the query parameters in the request
request.querystring Proxy request String Read Complete queryparam in request.For example : if the request is http://host.com/123?name=first&surname=second&place=address then this variable will return name=first&surname=second&place=address
request.transportid Proxy request String Read ID of the request as type TransportMessage which is a contextual object
request.transport.message Proxy request Transport Message Read Request of type TransportMessage which is a contexual object 
request.uri Proxy request String Read/Write The request path including query parameters
request.verb Proxy request String Read/Write The http verb used for the request. Ex: GET, PUT, DELETE
request.version Proxy request String Read/Write The http version of the request
response.formstring Target request String Read Complete formparam in response. Example: name=test&type=first&group=A
route.target Target request String Read Returns TargetEndpoint name
servicecallout.{policy-name}.expectedcn Proxy request String Read/Write Variable exposing a specific service callout policy' TargetEndpoint CN when it's running on SSL
servicecallout.{policy-name}.target.url Proxy request String Read/Write The TargetEndpoint url for a particular service callout policy
target.basepath Target request String Read Returns basepath of TargetEndpoint
target.basepath.with.query Target request String Read Returns basepath with queryparam of TargetEndpoint.
target.copy.pathsuffix Target request Boolean Read/Write When true, request forwarded from ProxyEndpoint to TargetEndpoint retains path sufffix (the URI path fragment following the URI defined in the ProxyEndpoint base path.)
target.copy.queryparams Target request Boolean Read/Write When true, request forwarded from ProxyEndpoint to TargetEndpoint retains query parameters.
target.cn Target request String Read Common name in the server SSL certificate evaluated by the TargetEndpoint
target.expectedcn Proxy request String Read/Write The common name expected by the TargetEndpoint on the server SSL certificate presented by the target service.
target.host Proxy request String Read Target host to which message is reaching from TargetEndpoint
target.name Target request String Read Target to which message is reaching from targetendpoint 
target.ip Proxy request String Read Target ip to which message is reaching from targetendpoint 
target.port Proxy request Integer Read Target source port which is connected to TargetEndpoint port for recieving request.
targetserver.name Target request String Read Target server name to which message is reaching from targetendpoint 
target.scheme Target request String Read/Write Returns http or https depending on the request message
target.sent.end.time Target request String Read Ending time of request sent to target from TargetEndpoint
target.sent.end.timestamp Target request Long Read Ending timestamp of request sent to target from TargetEndpoint
target.sent.start.time Target request String Read Starting time of request sent to target from TargetEndpoint
target.sent.start.timestamp Target request Long Read Ending timestamp of request sent to target from TargetEndpoint
target.ssl.enabled Proxy request Boolean Read Whether TargetEndpoint is running on SSL
target.url Target request String Read/Write Returns complete url sent from from TargetEndpoint including queryparam
variable.expectedcn Proxy request String Read/Write Variable exposed for CN if it's running on SSL
virtualhost.aliases Proxy request String_array Read Host aliases of the virtual host that is hit during a particular request
virtualhost.name Proxy request String Read Name of the virtual host that serves the originating client request
virtualhost.ssl.enabled Proxy request Boolean Read Returns true if SSL is enabled in the virtual host configuration

Response message variables

Response message variables include components such as status code, reason phrase, header, and XPath. The supported response message variables are listed below.

Response message variable Scope Type Permission Description
client.sent.end.time Proxy response String Read Ending time of the response when returned to the client at ProxyEndpoint
client.sent.end.timestamp Proxy response Long Read Ending timestamp of the response when returned to the client at ProxyEndpoint
client.sent.start.time Proxy response String Read Starting time of the response when returned to the client at ProxyEndpoint
client.sent.start.timestamp Proxy response Long Read Starting timestamp of the response when returned to the client at ProxyEndpoint
loadbalancing.failedservers Target response String_array Read List of failed TargetServers during load balancing at TargetEndpoint
loadbalancing.isfallback Target response Boolean Read Return true if fallback is enabled for the TargetServer invoked during load balancing at TargetEndpoint 
loadbalancing.targetserver Target response String Read TargetServer invoked during load balancing at TargetEndpoint 
message.reason.phrase Target response String Read ReasonPhrase of the response message from target
message.status.code Target response Integer Read HTTP status code of the response message from target
response Target response Message Read/Write Complete response message returned by target
response.content Target response String Read/Write Payload content of the response message returned by the target
response.formparam.{formparam_name} Target response String Read/Write The value of a form parameter in the response
response.formparam.{formparam_name}.values.count Target response Integer Read Count of all the values of the specified form parameter in response
response.formparams.count Target response Integer Read Count of all form prameters in the response
response.formparams.names Target response Collection Read The names of all the form parameters in the response
response.header.{header_name} Target response String Read Value of a specified HTTP header in the response
response.header.{header_name}.values Target response Collection Read All the values of a specified HTTP header in response
response.header.{header_name}.values.count Target response Integer Read Count of all the values of the specified HTTP header in response
response.headers.count Target response Integer Read Count of all the headers in the response
response.headers.names Target response Collection Read The names of all the headers in the response
response.reason.phrase Target response String Read/Write The response reason phrase for a particular request
response.status.code Target response Integer Read/Write The response code returned for a particular request
response.transport.message Target response String Read Response of type TransportMessage which is a contexual object 
target.country Target response String Read Country of the SSL certificate presented by the target server
target.email.address Target response String Read Email address of the SSL certificate presented by the target server
target.organization Target response String Read Organization of the SSL certificate presented by the target server
target.organization.unit Target response String Read Organization unit of the SSL certificate presented by the target server
target.locality Target response String Read Locality (city) of the SSL certificate presented by the target server
target.received.end.time Target response String Read Ending time of the response from the target at TargetEndpoint
target.received.end.timestamp Target response Long Read Ending timestamp of the response from the target at TargetEndpoint
target.received.start.time Target response String Read Start time of the response from the target at TargetEndpoint
target.received.start.timestamp Target response Long Read Starting teimstamp of the response from the target  at TargetEndpoint
target.state         Target response String  Read State of the SSL certificate presented by the target server

Path variables

Path variables are predefined variables that can be used to retrieve different parts of the request path.

Variables Path Description
Request variables request.uri The HTTP request path, which includes a path and a query string separated by a question mark ( ? )
request.path The HTTP request path without the query string
request.querystring The portion of the HTTP request path after the question mark ( ? )
Application variables application.basepath The deployment base path (specified during API deployment)
Proxy Variables proxy.basepath The base path as configured in the proxy XML file
proxy.pathprefix The portion of the request path after the proxy basepath
Target variables target.url The URL configured in the target XML file or the dynamic target URL (if target.url is set during the message flow)
target.basepath The path (without host or port) in the URL configured in the target XML file or the dynamic target URL (if target.url is set during the message flow)
target.basepath.with.query The path along with query params (without host or port) in the URL configured in the target XML file or the dynamic target URL (if target.url is set during the message flow)

Example

Consider the following deployment:

  1. Deployment path: /dev/
  2. Proxy base path: /twitter/
  3. Virtual host port: 8090
  4. Virtual host alias: mytwitter.com
  5. Target URL: http://api.twitter.com/1/

Request from client - The client makes the request:

            GET /dev/twitter/help/test.json
            curl http://{host}:8090/dev/twitter/help/test.json -H 'host: mytwitter.com'

The path is visualized as :

            {VERB} {application.basepath}/{proxy.basepath}/{proxy.pathsuffix}

Request is sent to target as:

            GET /1/help/test.json
            equivalent to:  curl http://api.twitter.com/1/help/test.json

The path is visualized as:

            {VERB} {target.basepath}/{proxy.pathsuffix}?{query params}

Usage in flows

Paths are usually used to classify requests as REST resources. This is achieved using conditional flows in a path match condition. Consider the following two requests based on the example above, which are two resources:

          GET /dev/twitter/help/test.json
          GET /dev/twitter/statuses/public_timeline.json

You can enforce different policies on these resources. The proxy.pathsuffix variable policy is recommended in conditions.

Note: You cannot use request.path because it includes the deployment path, which can change. The same bundle should work with different deployment paths.