Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/JonathanHerSa/xolo-api-hub/llms.txt

Use this file to discover all available pages before exploring further.

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.
FormExampleUse case
{{variable}}{{baseUrl}}/v1/usersStandard environment variable or dynamic helper
:param/users/:userId/postsURL path segment parameter
{:param}/orgs/{:orgId}/membersAlternate 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:
VariableDescription
{{$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.

Build docs developers (and LLMs) love

Get started for freeTalk to us