Using the API Test Step Builder
Last updated
Last updated
Due to recent platform-wide naming, navigation, and URL changes in the product, you may notice some discrepancies between the product and the screenshots displayed in our technical documentation. The instructions and actual pages in the product are still valid and haven’t changed. Please bear with us as we update our screenshots to better match the in-product experience. See the full scope of changes on Naming and Navigation Menu changes - Summary List.
The Step Builder is where most of the API test configuration occurs.
You can use the Step Builder to chain together API calls in a series of steps, each with its own API endpoint. You can extract variables from one API call for use in subsequent steps in the test. For example, obtaining a product SKU in one step and then using that SKU to fetch a price.
Each step corresponds to a single API call. Within each step, you can optionally specify additional information on a series of tabs:
Parameters - Specify one or more key-value pairs to include in the request's query string
Headers - Add custom headers if the API endpoint requires them.
Body - For POST or PUT methods, you can send a customized payload.
Assertion rules - The default is HTTP response success code 200, but you can actually look for or exclude specific error codes. You can also look for strings in the response such as a product code of “tigers” when the desired response is “kittens”.
Post-request options - Use this feature to extract variables from a response and pass them to subsequent steps within the same test.
Each step has a name, a number in the sequence, an API method, and an endpoint.
Name: Enter a short description of what this step in the API test is intended to do.
API Methods: Choose GET (default), POST, PUT, or DELETE.
Endpoint: The endpoint is a URL for the API call, for example https://api.thousandeyes.com/v6
Authentication Types supported are:
None - default
Basic - enter a username (plain text) and password (obscured) or use the Credentials Repository.
Bearer Token - enter a token (obscured) or use the Credentials Repository.
OAuth 2.0 - generates a new token for every test round.
Click the key icon to access your ThousandEyes Credentials Repository, as described in Working With Secure Credentials. You can find your ThousandEyes Credentials Repository under Network & App Synthetics > Test Settings > Credentials Repository.
Depending on your own environment and whose API you’re testing, you may not need to provide explicit authentication for each step in your test.
Don’t put user credentials in global predefined variables, parameters, or headers. Use the Authentication tab and the Credentials Repository.
Credentials should only be used in the Authentication tab, which automatically configures the Authorization HTTP request header. The ThousandEyes platform redacts/obscures the value of the Authorization header, whether or not a Credential was used from the Credentials Repository.
Verify SSL Certificate check box: choose whether to send a certificate for this API step. (To enable the use of certificates within this test, use the Advanced Settings tab from the Network & App Synthetics > Test Settings page.)
In OAuth 2.0, an HTTP request is sent to an authentication server in order to obtain a uniquely generated one-time token used for each test round, using a client ID and a client secret as credentials.
The Step Builder in ThousandEyes generates two steps for OAuth, each pointing to a different endpoint:
Step 1: Go to the OAuth URL endpoint to get a token, which is saved as a variable.
Step 2: Use that token to connect to the application’s endpoint URL.
The workflow is automated so that as soon as you choose OAuth 2.0 as the authentication method, the Step Builder automatically creates a Step 1 titled OAuth 2.0. A second step, which you will name, contains all the input information from both steps.
Most of this is set up on the Authentication tab in the Step Builder, and then you’ll use the Assertion Rules tab to specify what constitutes success. ThousandEyes automatically creates the variable and shows the variable name on the Authentication tab. You don't need to set post-request variables for the "Step 1 OAuth" request.
Note that the default Step 1 (the "OAuth 2.0" step) includes default assertions. These assertions cannot be modified for the OAuth 2.0 step.
HTTP response code is 200
Response body contains "access_token"
On the Authentication tab, provide the following information:
Token URL - Endpoint used for the OAuth authentication server. This endpoint is used to get the access token.
Client ID - Unique identifier for your application, provided by the API service when you register your application (equivalent to a username).
Client Secret - Confidential key that you use to authenticate with the OAuth server (equivalent to a password). Click the key icon to use a secret stored in your organization’s ThousandEyes Credentials Repository. See Working With Secure Credentials for more information.
Scope - A list of permissions that you are requesting. For example, read:org would request organization-wide read permission.
Client Authentication defines how your user credentials, namely your Client ID and Client Secret are sent in the authentication request. This field has two options:
Use Send as Basic Auth Header to send credentials in the request header.
Use Send Client Credentials in Body to send credentials in the request body.
The Parameters tab lets you specify a series of one or more key-value pairs to pass in as parameters to the API call defined for this step.
For example, the ThousandEyes API has a parameter named aid which is used to set the account group context. You can include this parameter in your API test by creating a parameter with a key of aid and the specific value of your choosing.
You can also use variables in parameter keys or values. Continuing with the aid parameter example above, you could:
Use one step to get a list of account groups and extract one account group ID. This ID would be assigned to a variable and passed to a later step to set the account group context of its request.
In a subsequent step, add a parameter with a key of aid, and pass in that {{aid}} variable as the value.
The Headers tab starts pre-populated with default headers, including a few custom built-in headers required in order for the ThousandEyes Cloud or Enterprise Agent that will be running this API test.
Note that:
The built-in headers for ThousandEyes can’t be modified.
You can use variables for header values, but not for header names. For example, you could add x-custom-header with {{my_var}}.
The Body tab is available for steps that use an API method of POST or PUT. Use this tab to send customized information to the test target.
Use the Assertion Rules tab to define one or more success factors for this one step, formatted as subject – operator – condition. It’s how you define what “good” looks like for this API. All assertion rules are ANDed together. Basically, assertion rules allow validation against HTTP responses to your API calls.
The default assertion rule for every step is a simple HTTP response status code from the API test target, which is 200 (OK). You can define more complicated assertion rules, depending on what API functionality you’re trying to monitor. For example, you might want to test an API and ensure that the API is not only up and responding, but that it’s correctly identifying unauthorized users.
An unsuccessful API test appears in the ThousandEyes test view with an error. These errors are related to the ThousandEyes API test itself, rather than errors issued by the API endpoints. You can set ThousandEyes alert rules to generate alerts, and also surface this test in the Dashboard.
Assertions are important for the Completion metric in the ThousandEyes API test view.
The Post-Request Options tab defines what happens at the end of this step when the API call is finishing up.
Collect response for this API step is a checkbox that causes the API response to be stored and made available on the ThousandEyes platform in the test view. Un-check if the response contains sensitive data.
Extract Variables using key-value pairs, to use them in subsequent API calls within this test.
You can add a Post-API-Call Delay in milliseconds. This is an arbitrary, artificial delay between this step and the next one. Adding a delay can be helpful if you know that you need a certain latency between one API call and the next, especially if you need to avoid race conditions.
The API test type expects variables to be passed between steps using JSON syntax.
Regarding the checkbox Collect Response for this API Step:
If you expect the API response to contain restricted data, de-select this option to keep the response on the ThousandEyes agent, and prevent it from being sent to the ThousandEyes platform. Sensitive data (anything that is subject to heightened regulatory or contractual handling requirements) should never be submitted to the ThousandEyes platform.
Variables in the API test type are key-value pairs, similar to credentials in the ThousandEyes Credentials Repository, except that ordinary variables are not secret.
Variables apply only to a single API test.The key is a name that you provide, and the value comes from one of the following places:
Another previous step in the same test
The Predefined Variables under Environment Setup in the Step Builder.
Use Predefined Variables to re-use a value that isn’t actually fetched in an API call. This is helpful when you want to parameterize a value throughout your API test rather than specifying the value over and over again. For example, when using the ThousandEyes API, suppose you are working in the context of an account group with an identifier of 1234.
Instead of explicitly providing the account group every time for each step:
You could create a predefined variable and name it my_aidand then use it in a complex multi-step API test as follows:
The Variables list on the Post-Request Options tab allows you to extract data from a step’s HTTP response, turn it into a named variable, and then reference that variable in subsequent steps. This feature is what allows you to chain API calls together.
For example, suppose you’re working with the ThousandEyes API, configuring a step that fetches the first user from a list within your own account group. You might see a response body similar to the one shown below:
The 245 portion from the above response could be extracted into a variable that you name my_user_id and you would then specify a value of users[0].uid.
