Web API tests

Web APIs are interfaces provided by a web server that can be used by a variety of clients like smartphone apps, rich-client applications, or other web applications. It is crucial to continuously ensure API performance, and with the Web API test category it is now possible to continuously monitor performance metrics for HTTP-based web service APIs.


Perform the following steps to execute a Web API test.

  1. Register a new test run through the REST interface using the webapi category.
  2. Send one or more HTTP requests to the URI page you want to test. These requests have to include the X-dynaTrace header where the test run ID returned by the AppMon Server REST Interface is specified to let AppMon know that these requests belong to a test. See below for a description of fields in the X-dynaTrace header.
  3. Analyze the test results in the Test Automation dashlet, or retrieve them using REST API.

In case you don't want to provide specific test metadata, you only need to provide the test name using the TN field in X-dynaTrace header (see below). That way the test run registers automatically.

X-Dynatrace header possible key-value pairs

The table lists possible key-value pairs. They can be provided in any order, separated with a semicolon.


The TN field should be used to provide test name. The TR and RC fields can still be used if you want to provide test run id or the expected response code.

Key Description Usage
TN Test Name (TN) should be provided using this field. Metrics for requests with the same name are aggregated. You can execute as many tests as desired within the same test run, but give them different names if they are not testing the same thing. Required.
You can still use NA and TR fields instead.
NA Old way of passing Test Na me. Deprecated
Requires TR field to be provided
TR TestRunId (TR), from a registered test run. See REST API POST testruns for more information. Optional when TN field us used. If not provided, a test registers automatically.
Required with NA field.
RC Expected Response Code (RC). If the test results in any other response code, the test is marked as failed. Optional. The default is 200.

X-Dynatrace header sample

Using test run id registered using Test Automation REST API, expecting 200 response code:

X-dynaTrace: TN=SampleTestName;TR=7a0520fc-eda9-4f78-a8fa-4cb7d04ac8b8;RC=200

Relying on automatic test run metadata registration (no test metadata provided), expecting default response code (200):

X-dynaTrace: TN=SampleTestName


Category Metric Name Notes
Web Requests Bytes Sent Request size capturing needs to be enabled in sensor's configuration. See Java Web Service sensor, Servlet sensor or Web Server sensor for more information.
Web Requests Bytes Received Request size capturing needs to be enabled in sensor's configuration. See Java Web Service sensor, Servlet sensor or Web Server sensor for more information.
PurePaths PurePath Duration
PurePaths PurePath Response Time
Methods Invocation All custom Method Invocation Measures that return a measure for a PurePath will be included
Logging Count
Exceptions Count
Database Execution Count

All the measures captured by the Test Automation feature must have agent and application splittings enabled.

To do this:

  1. Open the System Profile Preferences dialog box, and select the Measures item.
  2. Double-click the required measure to edit it.
  3. In the Details tab, expand the Measure splitting list and select the Create measure for each application and Create measure for each agent check boxes.
  4. Save your changes.


See Integrate Web API Performance Monitoring in JMeter for more information how to use the Web API test category.