# Getting Started with API Tests

## Prerequisites

This article assumes that you have previously read the following getting started documentation:

* [Getting Started with Account Setup](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-account-setup)
* [Getting Started with Cloud and Enterprise Agent Tests](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-cloud-and-enterprise-agent-tests)

## What is an API Test?

While some of the other ThousandEyes web layer test types can also perform basic API endpoint testing, they can’t test as deeply as the API test. An API test can look deeper within a single target domain and test various API calls, including passing values and parameters from one call to the next. It provides metrics specifically for measuring API performance and capabilities specifically for easier troubleshooting.

## API Test Use Cases

Here are some examples of how you can use the API test type:

* **IT operations:** Understand the state of key internal application APIs in order to pass along the scope and probable root cause of an issue to the team or vendor responsible for that particular feature.
* **Network:** Identify loss along the network path so that if there is an outage in a key API due to network issues, it’s easier to find the probable root cause.
* **Applications:** Understand the performance of all of the application APIs, in order to monitor application health

## Creating an API Test

### Basic Configuration

These instructions focus on the minimum required data for creating an API test. The first part is accessing test settings, as shown below.

First, open the test creation window:

1. Choose **Network & App Synthetics > Test Settings** and click the **Add New Test** button at the top of the screen.
2. Choose **Web** as the layer and **API** as the test type.

Optionally, Enter a test name and a description, and then continue to the basic test settings as shown below.

Next:

1. Click **Configure Target API** and enter at least one step in the Step Builder, as described in Part 2 below. The network target shown in the **Network Test Target** field is used for the network layer portion of this test (path visualization and network overview).
2. On the **Basic Configuration** tab, choose at least one Cloud or Enterprise Agent. If you choose one of your own Enterprise Agents, the Enterprise Agent must have BrowserBot installed.
3. Click **Run Once** to run an instant test.
4. Click **Create New Test** to save the test. The test will start running immediately.

After waiting a few test rounds, you can see test results in **Network & App Synthetics > Views**.

The API test type supports client certificate authentication, similar to all other web test types. For the API test type, this setting is found on the **Network & App Synthetics > Test Settings > Advanced Settings** tab. You can selectively disable this setting per API call in the **Authenticaion** tab of the Step Builder.

On the **Advanced Settings** tab, the **Specify Domain** is an input field that allows the use of wildcards (“\*”) to specify the domains to which the client certificate will be sent. For example `*.thousandeyes.com`. If this field is empty, the client certificate will be sent to *all* domains defined in the API step builder.

### Step Builder

These instructions focus on the minimum required data for creating an API test. The second part is adding a step using the Step Builder, as shown below. (Although the absolute minimum data entry required is a single step with an endpoint, realistically you’d configure a few more items for things like authentication or parameters as well.) For more information, see [Using the Step Builder](https://docs.thousandeyes.com/product-documentation/api-test/using-the-step-builder).

Continue in the Step Builder, under Step 1.

1. Enter a step name, for example “Status Check”.
2. Leave GET as the default selection on the drop-down.
3. Enter a **Request URL** of `https://api.thousandeyes.com/v7/status`. The first portion of the URL is the domain name of the Target API, which remains the same in all steps for this API test.
4. Click **Save Configuration** to return to the Test Settings configuration screen.

There’s one default assertion rule already in place for a generic “ok” status code 200, so you don’t need to add any for this basic exercise.

### Run an Instant Test and Save the Test Configuration

The last part before saving the test settings is to run an instant test to ensure that your API test is configured correctly. After completing the Step Builder, you’ll be back on the main test settings screen. From here, you’ll still need to complete the task of saving and enabling the API test.

Click **Run Once** at the bottom of the new test **Basic Configuration** tab.

* If all is well, you’ll see a test view window in a new browser tab, showing test results.
* If there’s a test configuration error that prevents the test from running at all, you’ll see a ThousandEyes error message.
* If the test was able to run but one of the values is wrong, for example the domain itself does not exist or the key-value pair was rejected or not recognized, there will be an error shown on the test view window itself.

At this point you can save the test by clicking the **Create New Test** button on the **Configuration** tab. The test will be enabled by default, which means it will run on the interval specified in the test settings. As the test runs, it will build up a history that you can see in the test view. If you don’t want to consume too many units, but you want to keep working on the test configuration later, you can also save the test configuration but deselect the Enable check box next to it on the Test Settings main screen.

## Interpreting Test Results

After creating an API test, you will want to look at the results. See [Reading the API Test Views](https://docs.thousandeyes.com/product-documentation/api-test/api-test-type-view) or, for more general information, [Getting Started with Views](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/viewing-data/getting-started-with-views).

## Additional Features

### Assertion Rules

Assertion rules determine what constitutes a minimally successful API test. When you configure a new API test, there’s a default rule already in place that specifies an HTTP status code of 200 (OK) which indicates that the HTTP request, in this case an API call, succeeded: the client requested something and the server provided it.

You can configure in the **Assertion Rules** tab of the Step Builder. See [Using the Step Builder](https://docs.thousandeyes.com/product-documentation/api-test/using-the-step-builder) for more information.

## Next Steps

For next steps, check out the following articles:

* [Getting Started with Dashboards](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-dashboards)
* [Getting Started with Views](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/viewing-data/getting-started-with-views)
* [Alerts](https://docs.thousandeyes.com/product-documentation/alerts)
* [Getting Started with Transactions](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-transactions)