Start monitoring today and get 20% off on your first invoice. Available on all Uptrends plans.

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:

Sourcepropertyvariable name

for example:

Response body as JSONaccess_tokenaccess_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, and inside assertions (response content checks). 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" }
  • In the target value of an assertion. For example, if you have a variable {{ProductId}} (populated in a previous step, or as a predefined variable), you can use it to verify that a response contains the actual value contained in that variable:

    Response body as JSON Products[0].Id Equals {{ProductId}}
  • In the property value of an assertion. If you have a variable {{ProductId}}, you can refer to that variable in a JSON expression or XPath query to select the content you're looking to verify:

    Response body as XML //Product[@Id="{{ProductId}}"]/Name/text() Equals Chocolate chip cookie

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, it's sometimes necessary to encode the values. Encoding means that we'll convert special characters to a format that is suitable for an HTTP request. Typically, variables that are used in a URL need to be encoded.For example, imagine you're building a URL that takes a name parameter, and you want to use a variable called CompanyName to specify a value for that parameter. Without considering encoding, you would use it like this:{{CompanyName}}

Now, suppose that the CompanyName variable contains the value Ben & Jerry's. That value contains spaces and an ampersand character, which have a special meaning in a URL. Without applying any encoding, you wouldn't get the correct value across to the server. If you apply encoding first, the value will be converted to Ben+%26+Jerry's, which will be interpreted by the server as the original value. To apply encoding to your variables, use the {{@UrlEncode(...)}} function. Inside the parentheses, include the full variable name, e.g. {{CompanyName}}. Used in a URL, it would look like this:{{@UrlEncode({{CompanyName}})}}

If a variable will never contain any special characters (for example, only numeric values), it's not necessary to use the @UrlEncode function.We'll automatically URL-encode variables used in the Request Body field of a step, but only if a Content-Type header has been specified with the value application/x-www-form-urlencoded. Other content types don't usually require URL encoding.

Automatic variables

Aside from variables you define in your monitor setup, you also have access to a number of automatic variables that we create for you. Most of them are actually functions that generate a value you can use in your HTTP requests, and during the evaluation of your HTTP responses using assertions.

The following automatic variables are available:

  • {{@DateTime(format,offset)}}: The @DateTime variable generates dynamic date and/or time values, according to the format you specify. The date/time is always the current time expressed in the UTC timezone. It's possible to generate dates/times/timezones by specifying the optional offset parameter, which adds/subtracts the specified number of seconds. For example, to convert the current UTC time to Eastern Standard Time (UTC-5), specify -18000 (-5 * 60 * 60) as the offset. Similary, to calculate "this time tomorrow" in UTC, specify 86400 (24 * 60 * 60). If you omit the offset value, no offset is applied. For example, if right now is 24 February, 2018 22:30 UTC, the following expressions would yield these results:
    {{@DateTime(dd-MM-yyyy HH:mm)}} 24-02-2018 22:30 Now
    {{@DateTime(ISO)}} 2018-02-24T22:30:00.0000000Z ISO 8601 format
    {{@DateTime(UNIX)}} 1519511400 Unix epoch time
    {{@DateTime(MM/dd/yyyy,-86400)}} 02/23/2018 Yesterday
    {{@DateTime(MM/dd/yyyy,86400)}} 02/25/2018 Tomorrow
  • {{@RandomGuid}}: 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 @RandomGuid 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.
  • {{@RandomInt(min,max)}}: This variable produces a random integer number, between the minimum and maximum values you specify (min and max included). For example, if you specify {{@RandomInt(0,100}}, this variable produces a number in the range 0..100.
  • {{@ServerId}}: 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.

Using an automatically generated value multiple times

Some of these variable functions (in particular the ones producing random and date/time values) are re-evaluated each time you use them, and will generate a new value every time. If you want to generate a particular value and use it multiple times throughout your multi-step scenario, you can define a predefined variable (as discussed in one of the previous sections) and use an automatic variable as its value.

Examples of predefined variables using automatic variables

Name Value Usage
SearchDate {{@DateTime(dd-MM-yyyy)}} A date value to be used as input for a search query.
UniqueEmail {{@RandomGuid}} A random guid value combined with fixed text to generate an e-mail address that is different every time.
OrderAmount {{@RandomInt(1, 10)}} A random number between 1 and 10 to be used as the number of products to order. In a subsequent call, you could use this variable again to check the contents of a shopping cart and see if it does indeed contain this amount.