Was this helpful?

Apigee Edge defines a set of variables that are available out-of-the-box. This document defines all of the variables the are "pre-defined" by API Services. 

Overview

Variables provide a rich context for API proxy development since they represent various aspects of a transaction on Apigee Edge. Every time an app submits a request to an API proxy, API Services 'populates' the values of variables with properties specific to the end-to-end transaction. 

API proxy developers can use variables to configure API proxies to do things dynamically--based on the values of the variables that are set. For example, an API proxy can route requests to different endpoints based on the source, the payload content, or the user-agent associated with a request message. A condition could be configured to check the value of the system.time variable, enabling a Quota 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.

For usage, see Flow variables and conditions.

Format

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 which 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.

Scope

Each variable defined below has an associated 'scope'. The scope is the point in the API proxy pipeline when the variable becomes available. For example, if you have a policy attached to the ProxyEndpoint request flow, that policy will not be able to access any variables that are scoped, for example, to the Target response.  The reason for this is that the target response phase of the flow has not executed yet, so the API proxy hasn't had a chance to populate the associated variables. When the policy executes in the ProxyEndpoint request flow, the API proxy has not yet invoked the backend service (the 'target'). For this reason, you need to make that your policies and code that make use of variables look for the variables in the scope where those variables will be available. Variables that are outside of the scope in which they are requested return 'undefined'.

References

A sample API proxy is available that demonstrates how to use a policy to Extract message content using ExtractVariables.

For an example of an API proxy configuration that uses variables to implement conditional behavior, see: Timer API proxy sample on GitHub.

For more information about variables in flows, see Flow variables and conditions.

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

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 app
client.country Proxy request String Read Country in the SSL certificate presented by the client app
client.email.address Proxy request String Read Email address in the SSL certificate presented by the client app
client.host Proxy request String Read HTTP host associated with 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 Edge.)
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 associated with the originating client request to ProxyEndpoint
client.received.end.time Proxy request String Read Ending time (UTC formatted) 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 time (UTC formatted) at which request is received from client app at ProxyEndpoint
client.received.start.timestamp Proxy request Long Read Starting timestamp at which request is received from client app at ProxyEndpoint
client.sent.end.time Proxy response String Read Ending time (UTC-formatted) at which the ProxyEndpoint returned the response to the client app.
client.sent.end.timestamp Proxy response Long Read Ending timestamp at which the ProxyEndpoint returns the response to the client app
client.sent.start.time Proxy response String Read Starting time (UTC formatted) at which the ProxyEndpoint returns the response to the client app
client.sent.start.timestamp Proxy response Long Read Staring timestamp at which the ProxyEndpoint returns the response to the client app
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 app to send the request message
client.ssl.enabled Proxy request String Read Returns true or false, depending on whether the ProxyEndpoint is configured for SSL
message.path Proxy request String Read/Write Complete request message path in URL excluding any query parameters. For example, where the ProxyEndpoint where the proxyRequest is http://api.apifactory.com/people/inventors?name=nikola&surname=tesla
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 count of a specific query parameter associated with the proxyRequest message
message.queryparams.count Proxy request Integer Read Total count of all query parameters associated with the proxyRequest message
message.queryparams.names Proxy request Collection Read A list of all query parameter names associated with the proxyRequest message
message.querystring Proxy request String Read A string containing all query parameter names and values associated with the ProxyRequest message. For example, where the proxyRequest is http://api.apifactory.com/inventors?name=nikola&surname=tesla, then this variable will return name=nikola&surname=tesla
message.uri Proxy request String Read Returns the complete URI path (following the domain URL) including query parameters. For example, where the proxyRequest is http://api.apifactory.com/inventors?name=nikola&surname=tesla, then this variable will return inventors?name=nikola&surname=tesla
message.verb Proxy request String Read Returns HTTP verb (GET, PUT, POST, DELETE, etc.) associated with the proxyRequest
message.version Proxy request String Read/Write Returns HTTP version associated with the proxyRequest
proxy.basepath Proxy request String Read/Write Returns the value of the basepath element for the API proxy in ProxyEndpoint that handles the proxyRequest
proxy.client.ip Proxy request String Read Returns the IP address associated with the HTTP request from the requesting app
proxy.pathsuffix Proxy request String Read The URI path fragment following the basepath associated with the ProxyEndpoint that handles the request message.
proxy.url Proxy request String Read/Write Returns complete URL associated with the proxy request message received by 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 the payload of the request message
request.formparam.{formparam_name} Proxy request String Read/Write The value of the specified form parameter in the request
request.formparam.{formparam_name}.values.count Proxy request Integer Read Count of all values for the specified form parameter associated with the request
request.formparams.count Proxy request Integer Read Count of all form parameters associated with the request
request.formparams.names Proxy request Collection Read A list of all form parameter names associated with 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

Message variables

Message variables are contextual: they refer to different message types (request, response, or error) depending on the point within the API Proxy Flow in which they are called. 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 referenced Message logging policy
messagelogging.failed Always Boolean Read Failure flag for Message logging policy
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 contextual object

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} {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.

Configuration variables

Configuration variables represent the configuration settings for an organization on Apigee Edge. 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 The revision number of an API proxy
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

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

SSL/TLS variables

The following variables are populated when an API proxy executes a transaction over inbound SSL/TLS. For the variables to be populated the property propagate.additional.ssl.headers must set to true in the ProxyEndpoint configuration.

For example:

<ProxyEndpoint name="myProxy">
  <HTTPProxyConnection>
  <BasePath>/v1/weather</BasePath>
  <VirtualHost>secure</VirtualHost>
  <Properties>
    <Property name="propagate.additional.ssl.headers">true</Property>
  </Properties>
</HTTPProxyConnection>

The variables are designed to be at parity with the Apache web server SSL settings.

SSL variable Scope Permission Description
ssl.protocol Proxy request Read See Apache Module mod_ssl.
ssl.session.id Proxy request Read See Apache Module mod_ssl.
ssl.cipher Proxy request Read See Apache Module mod_ssl.
ssl.server.m.version Proxy request Read See Apache Module mod_ssl.
ssl.server.m.serial Proxy request Read See Apache Module mod_ssl.
ssl.server.i.dn Proxy request Read See Apache Module mod_ssl.
ssl.server.i.dn.cn Proxy request Read See Apache Module mod_ssl.
ssl.server.i.dn.c Proxy request Read See Apache Module mod_ssl.
ssl.server.i.dn.o Proxy request Read See Apache Module mod_ssl.
ssl.server.i.dn.l Proxy request Read See Apache Module mod_ssl.
ssl.server.s.dn Proxy request Read See Apache Module mod_ssl.
ssl.server.s.dn.cn Proxy request Read See Apache Module mod_ssl.
ssl.server.s.dn.c Proxy request Read See Apache Module mod_ssl.
ssl.server.s.dn.o Proxy request Read See Apache Module mod_ssl.
ssl.server.s.dn.l Proxy request Read See Apache Module mod_ssl.
ssl.server.v.start Proxy request Read See Apache Module mod_ssl.
ssl.server.v.end Proxy request Read See Apache Module mod_ssl.
ssl.server.v.remain Proxy request Read See Apache Module mod_ssl.
ssl.server.a.sig Proxy request Read See Apache Module mod_ssl.
ssl.server.a.key Proxy request Read See Apache Module mod_ssl.
ssl.client.m.version Proxy request Read See Apache Module mod_ssl.
ssl.client.m.serial Proxy request Read See Apache Module mod_ssl.
ssl.client.i.dn Proxy request Read See Apache Module mod_ssl.
ssl.client.i.dn.cn Proxy request Read See Apache Module mod_ssl.
ssl.client.i.dn.o Proxy request Read See Apache Module mod_ssl.
ssl.client.i.dn.c Proxy request Read See Apache Module mod_ssl.
ssl.client.i.dn.l Proxy request Read See Apache Module mod_ssl.
ssl.client.s.dn Proxy request Read See Apache Module mod_ssl.
ssl.client.s.dn.cn Proxy request Read See Apache Module mod_ssl.
ssl.client.s.dn.o Proxy request Read See Apache Module mod_ssl.
ssl.client.s.dn.c Proxy request Read See Apache Module mod_ssl.
ssl.client.s.dn.l Proxy request Read See Apache Module mod_ssl.
ssl.client.v.start Proxy request Read See Apache Module mod_ssl.
ssl.client.v.end Proxy request Read See Apache Module mod_ssl.
ssl.client.v.remain Proxy request Read See Apache Module mod_ssl.
ssl.client.a.sig Proxy request Read See Apache Module mod_ssl.
ssl.client.a.key Proxy request Read See Apache Module mod_ssl.

Policy variables

Each Policy type defines a set of policy-specific variables. For details, see each Policy type under the Policy reference overview.

Add new comment

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.