Built-In Variables

Built-in variables in API7 Gateway are pre-defined variables that can be directly referenced in configurations. They are often used in plugin configurations, route matching, and log customization.

API7 Gateway supports three types of built-in variables:

• NGINX Variables
• APISIX Variables
• Custom Variables

These variables are evaluated in a given order.

NGINX Variables

NGINX provides variables that expose request and response information.

Commonly used variables include:

Variable	Description
upstream_addr	IP address and port, or UNIX-domain socket path, of the upstream server.
remote_addr	Client address.
request_method	Request method, such as GET or POST.
request_uri	Full original request URI, including arguments.
server_name	Name of the server that accepted the request.
status	Response status. It can be 000 until NGINX establishes the response status. Use it in response-phase contexts, such as Debug Session sampling rules or logging plugins; do not use it for route matching.
uri	Current normalized request URI, which can change during request processing.
http_user_agent	Value of the User-Agent request header.

See the complete list of NGINX variables for more information.

APISIX Variables

In addition to NGINX variables, APISIX offers a variety of built-in variables:

Variable Name	Description
post_arg_*	HTTP POST form data when the content type is application/x-www-form-urlencoded. The asterisk is to be replaced with the actual name of the POST form data.
post_arg.*	HTTP POST body parameter when the content type is application/json, application/x-www-form-urlencoded, or multipart/form-data. The asterisk is to be replaced with the actual name of the POST parameter. Supports JSON path-like selection, such as post_arg.model.version and post_arg.messages[*].content[*].type.
arg_*	URL query string. The asterisk is to be replaced with the actual query parameter name.
http_*	HTTP request header. The asterisk is to be replaced with the actual name of the header.
cookie_*	Request cookie. The asterisk is to be replaced with the actual name of the cookie.
method	HTTP request method, such as GET or POST. The equivalent NGINX variable is request_method.
balancer_ip	Upstream server IP.
balancer_port	Upstream server port.
consumer_name	Consumer username.
consumer_group_id	Consumer group ID.
graphql_name	GraphQL operation name.
graphql_operation	GraphQL operation type.
graphql_root_fields	GraphQL root fields.
route_id	Route ID.
route_name	Route name.
service_id	Service ID.
service_name	Service name.
resp_body	HTTP response body.
mqtt_client_id	Client ID in MQTT protocol.
redis_cmd_line	Redis command.
rpc_time	RPC request round-trip time.
external_user.*	External user information. This variable can be populated by authentication plugins such as openid-connect, making it available to other plugins. For example, limit-count-advanced can enforce rate limiting by username when key is set to ${external_user.preferred_username}.
upstream_unresolved_host	The configured upstream host or domain name before DNS resolution (the upstream node's domain or host). Available in API7 Enterprise from version 3.9.15.

caution

http_* reads an HTTP request header. It is not a prefix for other built-in variables. For example, http_uri, http_method, and http_status read request headers named Uri, Method, and Status. Use uri, method, and status for the request path, request method, and response status.

API7 Gateway does not verify that such a header exists when compiling an expression. If a client does not send the header, a condition that expects it to have a value can fail to match without an error.

Evaluation Order

API7 Gateway evaluates variables in the given order:

1. Custom Variables
2. APISIX Variables
3. NGINX Variables

If a variable is successfully sourced in custom variables, API7 Gateway will not continue to look in APISIX variables or NGINX variables.

In other words, custom variables will overwrite variables of the same names defined in APISIX variables or NGINX variables, to better meet requirements of your specific use cases.

Variable Syntax

A valid variable name can include letters, digits, underscores (_), and periods (.).

Escaped variables with a backslash (\) are not treated as variables, for example, \$variable_name.

Simple and Braced Forms

A variable can be referenced in two forms:

• $variable_name
• ${variable_name}

Both forms are supported; however, the braced form is required in certain contexts to ensure correct parsing.

The unbraced form $variable is valid when the following character cannot be part of a variable name. For example, the following forms are equivalent:

• $http_host and ${http_host}
• $arg_username-$arg_userid and ${arg_username}-${arg_userid}

When a variable is followed by a character that could belong to a variable name, the parser will incorrectly interpret it as a longer variable name. For example, with https://$http_baseurl.com, the parser would treat the entire string http_baseurl.com as the variable, which is incorrect. In this case, you should use the braced form https://${http_baseurl}.com to clearly delimit the variable.

You would also need the braced form if you use the ?? operator.

Default Values with ??

You can specify a default value for a variable using the ?? operator. If the variable is not defined, the value after the operator will be used.

Example	Behavior
${http_username ?? anonymous}	If the HTTP request header username is defined, its value is used; otherwise the string anonymous is used.
${http_count ?? 10}	If the HTTP request header count is defined, its value is used; otherwise the string 10 is used.