API Monitoring & Testing: Dynamic Request Data

Variables allow you to dynamically insert data into a request using built-in functions (timestamps, random strings, hashes), configuration data from environments and data extracted from a previous response in a test run. Data is inserted into requests using a simple template format.


Using Variables to Pass Data Between Steps (Chained Requests)

Request steps can define variables that extract data from HTTP responses returned when running the test. To create a variable, expand a request within your test, click 'Variables' and specify the location of the data you'd like to extract from the response. Lastly, pick a name to reference it in a subsequent request.

Source The location of the data to extract. Data can be extracted from HTTP header values, JSON, XML or text response bodies, and the response status code.
Property The property of the source data to retrieve. For HTTP headers this is the name of the header. For XML and JSON content, see below. Unused for text content and status code.
Variable Name The name of the variable to assign the extracted value to. In subsequent requests you can retrieve the value of the variable by this name. See Using Variables in Requests.

Extracting Data from JSON Body Content

Data from a JSON response body can be extracted by specifying the path of the target data using standard JavaScript notation. View sample JSON expressions.

Extracting Data from XML Body Content

Data from an XML response body can be extracted by specifying the path of the target data using XPath. In the 'Property' box of a variable definition that uses 'XML Body' as the source, enter an XPath expression to locate the data to extract and assign to the variable.


Environment Variables

Environments allow you to manage configuration on a per-test or per-bucket level. Common values (base URLs, API tokens, etc.) that are shared across requests within a test, or tests within a bucket, should be stored in an Initial Variable or Initial Script within an environment. Once defined, the variable is available to all requests within the test.

Initial Variables

Initial Variables specify data available to all requests in a test, including the first request. This can be useful for storing values that are common to all requests (like API keys) or other data required to set up the test run. Each test run will use the initial variables specified by the selected environment. To override variables on a per-run basis, use a Trigger URL with Custom Initial Variables.

Initial Script

Initial Scripts are executed before the first request in a test is made, but after the Initial Variables have been evaluated. variables.get() and variables.set() can be used to read and write variable values to be used by requests in the test. See: Scripts: Initial Script and Evaluation Order of Initial Variables.


Built-in Variables and Functions

In addition to the variables you define yourself, you can use these built-in variables and functions to generate common types of data.

Variable/Function Description Example Output
{{timestamp}} Integer Unix timestamp (seconds elapsed since January 1, 1970 00:00 UTC) 1384035195
{{utc_datetime}} UTC datetime string in ISO 8601 format. 2013-11-07T19:24:41.418968
{{format_timestamp(value, format)}} Timestamp of the specified value in the specified
format. Any delimiters (e.g. -, /, ., *, etc.) can
be used in the format with a combination
of any of the following date/time format
options. Also accepts variables. E.g.
{{format_timestamp({{timestamp}}, YYYY-MM-DD)}}
  • YYYY - 4 digit year (e.g. 2016)
  • YY - 2 digit year (e.g. 16)
  • MM - month
  • DD - day
  • HH - 24 hour (e.g. 13 == 1pm)
  • hh - 12 hour (e.g. 01 == 1pm)
  • mm - minutes
  • ss - seconds
2013-31-03
{{timestamp_offset(value)}} Integer Unix timestamp offset by the specified value in seconds (going back in time would be a negative offset value). Values should be passed without surrounding quotes. 1383948795
{{random_int}} Random integer between 0 and 18446744073709551615. 407370955
{{random_int(a,b)}} Random integer value between a and b, inclusive. 44674407370
{{random_string(length)}} Random alphanumeric string of the specified length (max 1000 characters). ddo1qlQR81
{{uuid}} Random universally unique identifier (UUID). 99386c08-6da7-4833-bb31-e70ce747c921
{{encode_base64(value)}} Encodes value in Base64. Values should be passed without surrounding quotes. Also accepts variables e.g. {{encode_base64({{username}}:{{password}})}} dTpwDQo=
{{md5(value)}} Generate an MD5 hash based on value. Values should be passed without surrounding quotes. Also accepts variables e.g. {{md5({{timestamp}})}} 50b7fe4da64720232c25bc7c6d66f6c5
{{sha1(value)}} Generate an SHA-1 hash based on value. Values should be passed without surrounding quotes. Also accepts variables e.g. {{sha1({{timestamp}})}} e0bd9304537cd8cb4e69ef5d73771fe218c484f5
{{sha256(value)}} Generate an SHA-256 hash based on value. Values should be passed without surrounding quotes. Also accepts variables e.g. {{sha1({{timestamp}})}} e3376ffb4b1e2c04b0fe68b52e8654696814b4883b47a56ff5a7df883725d8c1
{{hmac_sha1(value,key)}} Generate an HMAC using the SHA-1 hashing algorithm based on value and key. Values should be passed without surrounding quotes. Also accepts variables e.g. {{hmac_sha1({{timestamp}},key)}} 163a04cd86a82b948a7e85f0ed3cd3b5929a7d0c
{{hmac_sha256(value,key)}} Generate an HMAC using the SHA-256 hashing algorithm based on value and key. Values should be passed without surrounding quotes. Also accepts variables e.g. {{hmac_sha1({{timestamp}},key)}} eb0b5c5b2a04ac25ff52c886e115f2e60c0dd8d50bab076dc065e95f5fd37fb9
{{url_encode(value)}} Create a percent-encoded string suitable for URL querystrings. This is not required for URL or form parameters defined in the request editor which are automatically encoded. Only use this if you need to double encode a value in a URL or include a URL encoded string in a header value. This%20is%20100%25%20URL%20encoded.
{{runscope_environment}} The name of the environment used for this test run. prod
{{runscope_environment_uuid}} The unique ID of the environment used for this test run. ab34b187-bcde-4f41-9ec1-ff77e99aa2d6
{{runscope_bucket}} The bucket key for the Runscope Bucket the executing test is contained within. y0z5xkr1oa3m
{{runscope_bucket_name}} The name of the Runscope Bucket the executing test is contained within. Jumping Rabbit
{{runscope_test_uuid}} The unique identifier for the Runscope test. a8ea3ddd-73bb-435c-bc44-7c4bc8d99647
{{runscope_test_name}} The name of the Runscope test. Sample Test
{{runscope_region}} The region code indicating the location in which this test run was initiated. eu1
{{runscope_agent}} The unique identifier for the agent which is running the agent. Blank if run from a Runscope location. 83a24630-323d-501a-74a1-a7e51485ca12

Note: these built-in functions are only available in the web-based variable editor and not Scripts.

Request an additional built-in variable or function by contacting support.

When using a built-in variable in the value of an initial variable, the value will be generated once and remain constant across all the requests in a test (unless later overridden by another variable definition).

Overriding Built-in Variables

You can define a variable that uses the same name as a built-in variable or function. This will override the built-in value with the value extracted from the test response.


Using Variables in Requests

Once a variable has been defined, you can use it in any subsequent request. The test steps editor will display the 'Available Variables' that have been defined prior to the selected request. Variables can be used in any request data field including the method, URL, header values, parameter values and request bodies.

To include the value of a variable in a request, enter the name of the variable surrounded by double braces e.g. {{variable_name}}.

If a variable is undefined when a request using that variable is executed, the test will fail.


Evaluation Order of Initial Variables

Variables can be set at various points in the setup of a test run. At each step of the setup, a variable value specified in an earlier step can be overridden. Variables defined via Trigger URLs, Initial Scripts and Initial Variables will be evaluated in the following order:

  1. Variables defined in a shared environment (if the selected environment for a test run inherits from one).
  2. Variables defined in an individual test environment.
  3. Variables set via an environment-specific or a bucket-wide Trigger URL.
  4. Variables set using variables.set() in a shared environment's Initial Script.
  5. Variables set using variables.set() in an individual test environment's Initial Script.

Next: Managing Configuration with Environments →