Variables and Dynamic Values in Xolo

Variable substitution is at the heart of how Xolo turns static request definitions into live, data-driven API calls. Every field in a request — URL, headers, query parameters, and body — is passed through VariableParser.parse() immediately before the HTTP request is sent. The parser resolves environment variables, path parameters, and a set of built-in dynamic helpers in a single pass, so you never need to manually update values between requests or environments.

Syntax Forms

VariableParser recognises three distinct variable syntax forms. All three are resolved by the same parse() method, so they can be mixed freely within a single string.

Form	Example	Use case
`{{variable}}`	`{{baseUrl}}/v1/users`	Standard environment variable or dynamic helper
`:param`	`/users/:userId/posts`	URL path segment parameter
`{:param}`	`/orgs/{:orgId}/members`	Alternate path segment form

When the parser encounters a token it cannot resolve — because the variable name does not exist in the current environment — it leaves the original placeholder untouched in the output rather than replacing it with an empty string. This makes missing variables immediately visible in resolved URLs and logs.

Static Environment Variables

Static variables are key-value pairs you define in an environment (e.g., Development, Staging, Production). At send time, Xolo reads the active environment and supplies its variables as the resolution map passed to VariableParser.parse().

// Example variable map supplied to the parser
final variables = {
  'baseUrl': 'https://api.example.com',
  'userId': '42',
  'apiVersion': 'v2',
};

You define these in Environments → New Variable and switch between environments without changing any request definition.

Built-in Dynamic Variables

Dynamic variables are prefixed with $ and are computed fresh on every call to parse() — they do not require any value to be defined in an environment. The following helpers are built into VariableParser:

Variable	Description
`{{$timestamp}}`	Unix timestamp in milliseconds (e.g., `1718000000000`)
`{{$guid}}`	UUID v4 (e.g., `a3bb189e-8bf9-3888-9912-ace4e6543002`)
`{{$randomInt}}`	Random integer in the range 0–999
`{{$isoDate}}`	ISO 8601 date only, e.g., `2024-06-10`
`{{$isoDateTime}}`	Full ISO 8601 datetime, e.g., `2024-06-10T14:30:00.000`
`{{$randomEmail}}`	Random test email address, e.g., `user12345@xolo.test`
`{{$randomString:N}}`	Random lowercase alphanumeric string of length `N` (default 8)
`{{$randomIntRange:min:max}}`	Random integer in `[min, max]` inclusive

For the parameterised helpers, the arguments are encoded directly in the variable name:

{{$randomString:16}}       → "k4mzqj8nfwb3hx2p"
{{$randomIntRange:100:999}} → "742"

Use {{$randomEmail}} in registration tests to avoid duplicate-email errors on repeated runs. Because a new random address is generated on every request, you can run the same “create account” flow as many times as you like without hitting a uniqueness constraint.

Recursive Resolution

VariableParser supports up to three levels of nested variable resolution. This means a variable value can itself contain {{...}} placeholders that will be resolved against the same variable map. For example, if your environment defines:

scheme    = "https"
host      = "api.example.com"
baseUrl   = "{{scheme}}://{{host}}"

Then {{baseUrl}} resolves to https://api.example.com in a single parse() call. Xolo automatically detects when the resolved result still contains {{ markers and re-runs the parser (incrementing an internal depth counter), stopping when the output stabilises or depth reaches 3.

`VariableParser.parse()` and `parseMap()`

Both methods are static — no instance is needed.

/// Resolves all variable placeholders in a single string.
///
/// [input]     The template string, e.g. "{{baseUrl}}/users/:id"
/// [variables] Key-value map of environment + dynamic overrides
/// [depth]     Internal recursion counter; do not pass explicitly
///
/// Returns the input string with all resolvable placeholders replaced.
static String parse(
  String input,
  Map<String, String> variables, {
  int depth = 0,
})

/// Resolves variable placeholders in every key and value of a map.
///
/// [input]     A Map<String, dynamic> of headers or query parameters
/// [variables] Key-value map of environment + dynamic overrides
///
/// Returns a new map with all String keys and String values parsed.
static Map<String, dynamic> parseMap(
  Map<String, dynamic> input,
  Map<String, String> variables,
)

parseMap() iterates over every entry: if a value is a String, both key and value are passed through parse(); non-string values (e.g., integers in query params) are kept as-is with only the key resolved.

Code Example

The following URL template demonstrates static environment variables alongside a dynamic helper:

{{baseUrl}}/users/{{userId}}?ts={{$timestamp}}

Given the variable map:

final variables = {
  'baseUrl': 'https://api.example.com',
  'userId':  'usr_8a4c',
};

VariableParser.parse() produces:

https://api.example.com/users/usr_8a4c?ts=1718034512345

The {{$timestamp}} token does not need to appear in the variable map — it is computed by the parser itself on every call.

Get Started

Core Features

Authentication

Scripting & Automation

Import & Sync

Variables and Dynamic Values in Xolo

Syntax Forms

Static Environment Variables

Built-in Dynamic Variables

Recursive Resolution

`VariableParser.parse()` and `parseMap()`

Code Example

​Syntax Forms

​Static Environment Variables

​Built-in Dynamic Variables

​Recursive Resolution

​VariableParser.parse() and parseMap()

​Code Example

Syntax Forms

Static Environment Variables

Built-in Dynamic Variables

Recursive Resolution

`VariableParser.parse()` and `parseMap()`

Code Example