# Include API Calls in a Transaction Test

{% hint style="warning" %}
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](https://docs.thousandeyes.com/whats-new/naming-and-nav-phase-2-changes).
{% endhint %}

{% hint style="info" %}
Although you can use the instructions in this section to add API calls into a transaction test script, the [API test type](https://docs.thousandeyes.com/product-documentation/api-test/)is 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](https://docs.thousandeyes.com/product-documentation/api-test/api-test-use-cases)
{% endhint %}

[Transaction tests](https://docs.thousandeyes.com/product-documentation/browser-synthetics/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](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/transaction-scripting-reference#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](https://docs.thousandeyes.com/product-documentation/api-test/) 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](https://github.com/thousandeyes/transaction-scripting-examples/tree/master/API-transaction-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 **Network & App Synthetics > 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](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/getting-started/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`](https://www.npmjs.com/package/node-fetch) module. For detailed instructions, see [Using the node-fetch Module](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/use-cases/api-monitoring/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`](https://nodejs.org/api/net.html) module. For detailed instructions, see [Using the net Module](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/use-cases/api-monitoring/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`](https://nodejs.org/api/tls.html) module. For detailed instructions, see [Using the tls Module](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/use-cases/api-monitoring/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?

![](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-8bb479170dfc8b12ef0efe1a965f2500074f1208%2Fapi-monitoring-data-view-example.png?alt=media\&token=75598ea5-2ecf-4abd-b7b9-adbfe1ea14e6)

For transaction tests that include API monitoring, you can see the test data on **Network & App Synthetics > 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.