Variables

In Headrest, to use variables, you need to:

1. Define a variable
2. Set a value to the variable
• It can be a default value or
• It can be a dynamic value from a response
3. Use the variable when making a request

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:

1. Determine the scope of the variable, where it can be a global or project variable.
2. Set a unique name for the variable, within its scope.

Click the 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.

Click the + 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).

Finally click 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.