API tests are useful to help you monitor your API endpoints and alert you when they are failing or too slow. These checks verify that your applications are responding to requests, as well as that they meet any conditions you define—such as response time, HTTP status code, and header or body contents. Use the Datadog API to see the full list.
API tests configuration depends on the type of API test you want to create. There are two API test types: HTTP test and SSL test.
Define the HTTP or SSL request you want to be executed by Datadog:
Define the request you want to be executed by Datadog:
HTTPChoose the Method and URL to query. Available methods are: GET, POST, PATCH, PUT, HEAD, DELETE, and OPTIONS.
text/plain, application/json, text/xml, text/html, or None)<COOKIE_NAME1>=<COOKIE_VALUE1>; <COOKIE_NAME2>=<COOKIE_VALUE2>.Name: The name of your API test.
Select your tags: The tags attached to your browser test. Use the <KEY>:<VALUE> format to filter on a <VALUE> for a given <KEY> on the Synthetics page.
Locations: The Datadog managed locations to run the test from. Many AWS locations from around the world are available. The full list is retrievable through the Datadog API. You can also set up a Private Location to run a Synthetics API test on a private endpoint not accessible from the public internet.
How often should Datadog run the test? Intervals are available between every one minute to once per week.
Click on Test URL to try out the request configuration. You should see a response preview show up on the right side of your screen.
SSLHost and the SSL Port. By default, the port is set to 443.<KEY>:<VALUE> format to filter on a <VALUE> for a given <KEY> on the Synthetics page.Set alert conditions to determine the circumstances under which you want a test to send a notification alert:
When you set the alert conditions to: An alert is triggered if any assertion fails for X minutes from any n of N locations, an alert is triggered if:
The uptime bar is displayed differently on your test result: location uptime is displayed on a per-evaluation basis (whether the last test was up or down). Total uptime is displayed based on the configured alert conditions. Notifications sent are based on the total uptime bar.
Note: You can decide the number of retries needed to consider a location as failed before sending a notification alert. By default, Synthetics tests do not retry after a failed result for a given location.
If one of the assertions defined fails for a given location, an alert is triggered.
When running an API test, you must define at least one assertion that should be monitored by Datadog. An assertion is defined by a parameter, an optional property, a comparator, and a target value.
| Type | Operator | Value type |
|---|---|---|
| Status Code | is, is not | Integer |
| Response time | lessThan | Integer (ms) |
| Headers | contains, does not contain, is, is notmatches, does not match | String Regex |
| Body | contains, does not contain, is, is notmatches, does not match | String Regex |
If you click on Test URL, then the basic assertions are automatically filled:
Response time lessThan 2000 msHeader content-type is “returned value”Status code is “returned value”| Type | Operator | Value type |
|---|---|---|
| certificate | expires in more than | Integer (number of days) |
| property | contains, does not contain, is, is notmatches, does not match | String Regex |
If you click on Test URL, then the basic assertion is automatically filled:
certificate expires in more than 10 daysYou can create up to 10 assertions per API test by clicking on Add new assertion or by clicking directly on the response preview:
A test is considered FAILED if it does not satisfy its assertions or if the request failed for another reason. These reasons include:
| Error | Description |
|---|---|
CONNRESET | The connection was abruptly closed by the remote server. Possible causes include the webserver encountering an error or crashing while responding, loss of connectivity of the webserver, etc. |
| DNS | DNS entry not found for the check URL. Possible causes include misconfigured check URL, wrong configuration of your DNS entries, etc. |
INVALID_REQUEST | The configuration of the check is invalid (e.g., typo in the URL). |
SSL | The SSL connection couldn’t be performed. See the dedicated error page for more information. |
TIMEOUT | The request couldn’t be completed in a reasonable time. Two types of TIMEOUT can happen. A TIMEOUT: The request couldn’t be completed in a reasonable time. indicates that the timeout happened at the TCP socket connection level. A TIMEOUT: Retrieving the response couldn’t be completed in a reasonable time. indicates that the timeout happened on the overall run (which includes TCP socket connection, data transfer, and assertions). |
If a test fails, the uptime directly considers the endpoint as down. It is not re-tested until the next test run.
You can use the global variables defined in the Settings in the URL, Advanced Options, and in the assertions of your API tests. To display your list of variables, type {{ in your desired field.
A notification is sent according to the set of alerting conditions. To configure notifications:
@-notifications are available in the message field, similar to monitors.Enter a message for the API test. This field allows standard Markdown formatting and supports the following conditional variables:
| Conditional Variable | Description |
|---|---|
{{#is_alert}} | Show when monitor alerts |
{{^is_alert}} | Show unless monitor alerts |
{{#is_recovery}} | Show when monitor recovers from either ALERT |
{{^is_recovery}} | Show unless monitor recovers from either ALERT |
Notification messages include the message defined in this section and information about which assertion failed and why.
Specify a renotification frequency. To prevent renotification on failing tests, leave the option as Never renotify if the monitor has not been resolved.
Click Save.
Notifications example:
The Synthetics details page displays the following network timings:
| Timing | Description |
|---|---|
DNS | Time spent resolving the DNS name of the last request. |
Connect | Time spent establishing a connection to the server. |
SSL | Time spent for the TLS handshake. If the last request is not over HTTPS, this metric does not appear. |
TTFB (time to first byte) | Time spent waiting for the first byte of response to be received. |
Download | Time spent downloading the response. |
Response time is the sum of these network timings.
On this Page
