In Headrest, to use variables, you need to:
- Define a variable
- Set a value to the variable
- It can be a default value or
- It can be a dynamic value from a response
Define a variable
Variables need to be defined before setting a value or using them. To define a variable, there are two thing you need to do:
- Determine the scope of the variable, where it can be a global or project variable.
- Set a unique name for the variable, within its scope.
Use variables link under the request URL to open the Variables modal.
Click either the
New project variable or the
New global variable button and give it a name. The name must be unique within its scope so the same name cannot be used for multiple variables in the same project or globally. Variables with the same name are allowed in separate projects or in the global scope.
Setting a variable
Variable can take values from two sources, either a default value or a dynamic value from a response.
After creating a new variable, you can immediately set a default value for it, on a per-environment basis.
Click the variable name in the Variables modal to expand it and set its default values for each environment.
Setting the value dynamically from a response
To set the value of a variable from a response, you need to use the
Set variables action in the response editor.
The variable needs to be in scope of a request. This means that the variable is either declared as global or declared on the same project as the request from which it is being used.
+ button and select the variable you want to set.
The value can be set dynamically from a JSON response using JSONPath. Click the
Evaluate link to see its value (or just press Enter in the JSONPath field).
Set and the variable will be set to the value from the response.
Every time the request is made, the variable will be set again based on the evaluation of the JSONPath expression.
Please note that variables can only be set dynamically from JSON responses. Other response types are not supported.
Using a variable
A variable can be used in the request URL, headers, body, and query params.
Use the double curly braces
}} notation to refer to a variable. If, for example, you need to use the
MY_VARIABLE, the syntax would be:
You can inspect the current value of a variable in the
Use variables modal, buy expanding the variable and check the You can inspect the current value of a variable in the
Use variables modal, buy expanding the variable and check the
Current value column for the current environment.
Clicking the copy icon in front of the variable will copy the variable to the clipboard and close the modal.
Evaluating the value of a variable
When referencing a variable, its value will be determined this way:
- Look for a value set dynamically on the variable with the given name from the same project of the request you're making, on the selected environment.
- If no value is found, look for a default value for the variable in the same project and on the selected environment.
- If a variable with that name is not defined in the project scope, look in the global scope.
- Look for a value set dynamically on the variable with the given name in the global scope, on the selected environment.
- If no value is found, look for a default value for the variable in the global scope and on the selected environment.
Values from variables that are set in another project or in another environment will not be used.
Environments and Variables
Variables work best when paired with environments. Read about using environments in Headrest.