In a multi-step API monitoring setup, variables are typically used to extract values from your HTTP responses and temporarily store them, so you can use them again in a later step. This essentially lets you link steps together: every time you want to take a piece of information from an HTTP response and use that information to execute the next HTTP request, you'll need a variable. Simply put: Step 1 receives a value from your server and stores it in a variable. Step 2 then takes the value we just stored and uses it to build up a new request. You can use as many variables as you want, and use them in as many steps as you need.

A second reason to use variables is to define certain values just once, and re-use them in several steps. You will typically add those values in the Predefined variables section: those variables are available in any step throughout the entire multi-step scenario. See the Predefined variables section for more information.

All variables you define in a step are evaluated as soon as the HTTP request has been executed and the response has been processed. At that point, if a variable already existed (either through a previous step, or because you predefined it), its existing value will be overwritten. Otherwise, a new variable is created and added to the list. This list of variables and corresponding values will then be carried across to the next step.

Defining variables

If you want to use variables, you'll need to tell us which value we should store in that variable. Similar to the pattern used to define assertions, variables are defined in the following way:

Source property variable name
for example:
Response body as JSON access_token access_token
  • The variable source: this field defines which attribute of the HTTP response you want to extract. Each available option is outlined in this article.
  • The variable property: some source options (in particular the content extraction and header related options) require you to further specify which content or header to check. This is explained in more detail for each appropriate source type.
  • The variable name: this is the identifier that will be used in subsequent steps to refer back to this variable, using a special notation.

If a problem occurs during the evaluation of a variable (for example, because you're trying to extract a value that is not present in the response content), the step will fail and an error will be reported.

Referring to variables in other steps

Once a variable has been evaluated successfully, its value can be re-used in the request definition of subsequent steps. Always refer to a variable by enclosing the variable name in double curly braces: {{variable-name}}.

  • In the URL of a step:{{ProductId}}
  • In a Request header: Authorization: Bearer {{access_token}}
  • In Request Body content:

    { "ProductId": "{{ProductId}}", "Code": "P123456" }

Predefined variables

Below the step editor, you'll find an additional section where you can specify more variables. These variables are available right at the beginning of the entire scenario. If you need a particular value several times, you can define that value in advance and use it in different steps. This could be a product Id you want to use throughout your scenario, an API key, or other special values your API needs.

One special case is to use a variable that holds the domain name for each API. By using that variable as part of each URL, you don't have to repeat it in each step, allowing you to change it very easily for the entire scenario.

To do this, create a variable named BaseUrl with value Using a reference to that variable, the URL for each API step could then take the form {{BaseURL}}/UserService/GetUserInfo. This approach allows you to change your multi-step scenario to point to a different environment (e.g. staging environment vs. production environment) without having to change each step.

It's important to use the name BaseUrl, because we need to treat it a little differently from other variables, as explained below.

Encoding of variable values

Depending on where you use your variables, we need to apply some encoding rules on the corresponding values. Encoding means that we'll convert special characters to a format that is suitable for an HTTP request. For example, if you have a variable called CompanyName with a value Ben & Jerry's, we'll automatically convert it to Ben+%26+Jerry's if needed.

We'll follow these rules:

  • We'll URL-encode variables used in the URL field of a step
  • We'll URL-encode variables used in the Request Body field of a step, only if a Content-Type header has been specified with the value application/x-www-form-urlencoded.
  • We will NOT URL-encode the variable called BaseUrl, because the domain name part of a URL should not be encoded.

That last rule explains why our BaseUrl example is special: the colon and forward slash characters in a value should never be encoded.

Automatic variables

Aside from variables you define in your monitor setup, you also have access to a number of automatic variable that we create for you. Those variables are:

  • Random-Guid: This variable produces a random value in the form AB0AD14D-9611-41A8-9C25-7D94B895CFF1. You can use this variable if you need to include a random value in your URL, POST data or HTTP header.
    If you use the Random-Guid variable in multiple steps, each step will get a different random value. Each time the monitor is executed, you will get completely new random values.
  • Checkpoint-Server-Id: During execution of a Multi-step API monitor, this variable outputs a numeric value that identifies the Uptrends checkpoint location that is executing that check.
    For example, if the check is being executed on our checkpoint in Sydney, Australia, the variable will output 30. The list of checkpoint servers and their corresponding Server IDs is available through the Uptrends API at the Checkpointservers endpoint.
  • RedirectUrl: In case any of the steps in your monitor are expected to return a redirect code, and you want to capture and test that redirect response, rather than automatically following it, this automatic variable will contain the URL the redirect is referring to.
    This will only happen if you choose not to auto-follow redirects, but set up an Assertion that checks for the appropriate redirect code. This procedure is explained in more detail here: How to handle redirects in multi-step monitoring.