Include API Calls in a Transaction Test

Although you can use the instructions in this section to add API calls into a transaction test script, the API test typeis a more robust way for the user to achieve this aim if you don’t need to include browser emulation, and only need the API calls. If you’re not sure which test type to use for a given use case, see Use Cases for API Test Type

Transaction tests mimic user journeys through web applications. But user journeys include more than in-app user clicks. They can also involve machine-to-machine interactions, in the form of API calls. You can use a ThousandEyes transaction test to monitor any API endpoint that you have access to.

When you need to monitor API calls at a granular level, whether to a third-party API or your own microservices, you can use the ThousandEyes synthetic testing framework to emulate conditional backend interactions with API endpoints, using markers to capture transaction times for each call. You can then use the ThousandEyes alerting and reporting capabilities to display the ongoing API monitoring results alongside other test data.

For example, a user interaction could use OAuth 2, a multi-step authentication protocol that involves obtaining a token from one system, and then passing that token to a second system, without the user having to manually provide their credentials during the transaction itself. A transaction test monitor for errors in each of those systems separately.

Note the following:

• Although it’s technically possible to mix API calls and a browser-generated script in a single transaction test, generally speaking a transaction test should focus on either one approach or the other.

• To capture transaction times for each API call, you’ll need to add markers for each API call into your script.

• Although you can use the instructions in this section to add API calls into a transaction test script, the API test type is a more robust way for the user to achieve this aim if you don’t need to include browser emulation, and only care about API performance.

Comparing Browser Synthetics and API Monitoring

ThousandEyes web transaction tests covers two main areas: browser synthetics, and API monitoring.

• A browser synthetics test includes a written or generated script that simulates a user’s journey within a browser. When that script is run in a transaction test, the transaction test view shows detailed measurements of each step in the workflow on the Waterfall tab.

• An API monitoring transaction test also includes a script, but this time the script monitors machine-to-machine interactions that occur outside of a browser. Your script simulates these back-end interactions, and measures the availability and performance of API endpoints.

Use Cases for API Monitoring

Why use a transaction test for API monitoring at all, when you could set up a simpler test to verify that your API gateway is available? Although other ThousandEyes tests exist for basic connectivity, HTTP server response, or page load times, a ThousandEyes transaction test provides transaction-level monitoring so you have better visibility into each step of your API’s performance.

Consider the following common situations when you would use API monitoring:

• Authentication

  Test the authentication step in a workflow where the authentication involves a multi-step protocol such as OAuth 2.

• Output-to-input

  Take the response from one API endpoint, and use it in the request body for another API endpoint. For example, fetching a list of SKU records from a sales order, and then requesting further details for a particular record from that list.

• API gateways

  Measure the performance of your own or a third-party API gateway, particularly if the APIs are served in a hybrid cloud environment.

• Validate API response

  Although you can use a ThousandEyes HTTP server test to monitor basic server availability, there are times that the HTTP response code alone is not sufficient to pinpoint performance or functionality isses. In this case, you might need to use a transaction test that allows you to inspect the API endpoint's response body.

• Dynamic request parameters

  Generate request parameters at runtime. For example, to exercise an API endpoint that supports a timestamp parameter, your ThousandEyes transaction test can generate a timestamp value to use in the request.

Creating API-Monitoring Tests

Unlike other transaction tests, you don’t use the ThousandEyes IDE Recorder to generate the test script. Instead, you can either write your own, or use one of the sample API scripts from the ThousandEyes scripting repository as a starting place. You’ll have to modify the sample values and credentials used in these script examples.

Steps to Create an API Monitoring Transaction Test

1. Create your test script, either from scratch or by modifying one of the example scripts.

2. On the ThousandEyes platform, go to Cloud & Enterprise Agents > Test Settings and click Add New Test. Choose Web as the layer and Transaction as the test type.

3. Add your script contents into the Transaction Script window on the Basic Configuration tab by doing one of the following:

   • Pasting in the contents of your .js transaction script file.

   • Selecting Import from JS File on the Test Configuration screen under the Create New menu button.

4. If your script requires a credential, do one of the following:

   • Create a new credential as described in Working With Secure Credentials.

   • Rename the credential name in the transaction script to use an existing credential that you had previously saved in your ThousandEyes Credentials Repository.

5. On the Basic Configuration tab, use the Credentials button (the key icon) to list the available credentials, and check a credential to select it. Make sure your credential name in the Credentials Repository matches what's used in the transaction test script.

6. Configure other required test settings, click Run Once to make sure the test works, and then save the test. ThousandEyes recommends starting with 3-5 agents, and using Round Robin testing with 10/1 minute test intervals.

Using the JavaScript Modules

There are three JavaScript modules useful for API monitoring. One, node-fetch, is open source, while the other two are from ThousandEyes.Consider the following actions that your transaction test script might include:

• HTTP requests

  Transaction test scripts can make requests against one or more HTTP API endpoints, and can chain data from one call to the next, if needed.

  To include this kind of monitoring in your script, you'll use the node-fetch module. For detailed instructions, see Using the node-fetch Module.

• TCP connections

  Transaction scripts can establish TCP connections to network targets, and can send arbitrary data (without application-layer awareness).

  To include this kind of monitoring in your script, you'll use the net module. For detailed instructions, see Using the net Module.

• TCP connections with TLS

  Transaction scripts can establish TCP connections to network targets that are secured with TLS.

  To include this kind of monitoring in your script, you'll use the tls module. For detailed instructions, see Using the tls Module.

Viewing API Monitoring Data for Transaction Tests

Unlike an ordinary ThousandEyes transaction test, which is a true “browser synthetics” simulation of an end-user’s browser experience, a transaction test script consists solely of API calls which are executed outside of a browser altogether. So, on the ThousandEyes platform, where in the test view will this test data appear?

For transaction tests that include API monitoring, you can see the test data on Cloud & Enterprise Agents > Views in the Transaction view:

• On the timeline view, any markers you define appear alongside the predefined metrics such as Transaction Time.

• On the Map tab, the summary area shows total transaction time. Basic error reporting for each agent appears when hovering over the agent’s location.

• On the Table tab, you might see API responses under the Errors and Warnings column.