Variables are the building blocks of conditions. They can be used to store data that is evaluated by a condition. There are pre-defined variables that are automatically populated as traffic flows through your API. For example, the system variable contains host name, data, and time values whenever a message is sent to your API. You can also choose to define your own variables that you can use to store information specific to your organization such as price.
Detailed information about the specific variables used and accessible by different policies is explained in the context of each of the policies. See the Policy Reference.
Pre-defined and user-defined variables
Predefined variables
A number of pre-defined variables are used in Apigee and they are categorized based on "functionality" or the "source" that provides the information for the variable. The categories are:
- System: System information such as host name, data, and time.
- Configuration: Information about an application's configuration such as account.name, application.name, proxy.name, target.url, and policy properties.
- Message: A contextual object, the same as "request" in the request flow, "response" in the response flow, or "error" in the error flow.
- Policy: Variables created as a result of policy executions.
- Request Message: The parts of a request message such as header, query param, form param, source IP, and XPath.
- Response Message: The parts of a response message such as status code, reason phrase, header, and XPath.
For details about the variables in each category, see the Variables reference.
User-defined variables
User-defined variables are those that are defined and used by an app. This is done by setting and getting variables into and from a message.
Data types
Pre-defined variables have defined data types like boolean, int, float, double and long.
User-defined variables do not have a defined data type unless the variable is set using Python or JavaScript, where the type can be specified by those languages.
Naming conventions
Pre-defined variables
All pre-defined defined variables follow a "dotted" convention. For example system.time.month, message.headers.count, target.name, and so on.
Each segment in the variable name indicates the scope of the variable.
All the variable names contain lower case letters.
See the Variables reference for details.
User-defined variables
Ensure that the name does not start with any of the pre-defined variables.
We recommend that you avoid using the "dotted" notation for user-defined variables as it may conflict with a pre-defined variable.
Scope, visibility, and access
The scope of a variable specifies where it is available or visible within the life cycle of the message processing. All variables have their own scope. For example,
- target.url is available only after the routes have been evaluated. It is available at the target request flow.
- system.time is always available irrespective of the state of the flow.
- response.* variables are available only after receiving a response from the target or cache.
- error.message is available only if the flow is proceeding in the error flow.
Variable_access indicates whether a variable is read-only or read-write.
Referencing variables
Some policies require a reference to a variable. For example:
Extract data into a variable: The convention is to refer to the variable as "{variable_name}". This is mainly used in the Extract Variables policy.
Substitute the value of a variable: The convention is to refer to the variable as "{variable_name}". This is mainly used in message templates.
Refer to a variable in a policy: The convention is to refer to the variable in the element's text. The configuration processor takes care of trimming the value.
Comparing variables
Whenever two variables are used for comparison (for example, in condition logic), they need to be adapted to the same data type. For example, compare an integer to an integer.
Resolving variables
If a variable cannot be resolved, a null value is returned. Some policies support ignoring unresolved variables by specifying the ignoreUnresolvedVariables parameter.
When ignoreUnresolvedVariables is set to true, and the value retrieved for the variable is null, then it is ignored rather than treated as an error. The following example scenarios summarize the behavior of unresolved variables:
- ignoreUnresolvedVariables is false and the variable get resolved: No issues
- ignoreUnresolvedVariables is false and the variable is not resolved: Treated as error
- ignoreUnresolvedVariables is true and the variable get resolved: No issues
- ignoreUnresolvedVariables is true and the variable is not resolved: Not treated as error, but a value of "" is substituted in text
setVariable and removeVariable
These variables are automatically set when errors occur:
Set variable (setVariable): When an incompatible data type is provided or set as the value for a variable, it is ignored and a false is returned to indicate that the set is ignored.
Remove variable (removeVariable): A value false is returned when a variable is removed to indicate that the variable could not be found and resolved.
