New announcements for Serverless, Network, RUM, and more from Dash! New announcements from Dash!

API Tests

Overview

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.

Configuration

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.

Make a request

Define the HTTP or SSL request you want to be executed by Datadog:

Define the request you want to be executed by Datadog:

  1. Choose request type: HTTP
  2. Choose the Method and URL to query. Available methods are: GET, POST, PATCH, PUT, HEAD, DELETE, and OPTIONS.

    • Advanced Options (optional): Use custom request headers, authentication credentials, body content, or cookies.
      • Follow Redirects: Toggle to have the monitored endpoint follow up to ten redirects.
      • Headers: Defined headers override the default browser headers. For example, set the User Agent in the header to identify Datadog scripts.
      • Authentication: HTTP basic authentication with username and password
      • Body: Request body and body type (text/plain, application/json, text/xml, text/html, or None)
      • Cookies: Defined cookies are added to the default browser cookies. Set multiple cookies using the format <COOKIE_NAME1>=<COOKIE_VALUE1>; <COOKIE_NAME2>=<COOKIE_VALUE2>.
  3. Name: The name of your API test.

  4. 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.

  5. 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.

  6. How often should Datadog run the test? Intervals are available between every one minute to once per week.

  7. 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.

  1. Choose request type: SSL
  2. Specify the Host and the SSL Port. By default, the port is set to 443.
  3. Name: The name of your API test.
  4. 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.
  5. 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.
  6. How often should Datadog run the test? Intervals are available between every five minutes to once per week.
  7. Click on Test Connection to try out the request configuration. You should see a response preview show up on the right side of your screen.

Alert Conditions

Set alert conditions to determine the circumstances under which you want a test to send an 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:

  • At least one location was in failure (at least one assertion failed) during the last X minutes, AND
  • At one moment during the last X minutes, at least n locations were in failure

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.

Assertions

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.

TypeOperatorValue type
Status Codeis, is notInteger
Response timelessThanInteger (ms)
Headerscontains, does not contain, is, is not
matches, does not match
String
Regex
Bodycontains, does not contain, is, is not
matches, does not match
String
Regex

If you click on Test URL, then the basic assertions are automatically filled:

  • Response time lessThan 2000 ms
  • Header content-type is “returned value”
  • Status code is “returned value”
TypeOperatorValue type
certificateexpires in more thanInteger (number of days)

If you click on Test URL, then the basic assertion is automatically filled:

  • certificate expires in more than 10 days

You can create up to 10 assertions per API test by clicking on Add new assertion or by clicking directly on the response preview:

Test Failure

A test is considered FAILED if it does not satisfy its assertions or if the request failed for another reason. These reasons include:

ErrorDescription
CONNRESETThe 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.
DNSDNS entry not found for the check URL. Possible causes include misconfigured check URL, wrong configuration of your DNS entries, etc.
INVALID_REQUESTThe configuration of the check is invalid (e.g., typo in the URL).
SSLThe SSL connection couldn’t be performed. See the dedicated error page for more information.
TIMEOUTThe request couldn’t be completed in a reasonable time.

If a test fails, the uptime directly considers the endpoint as down. It is not re-tested until the next test run.

Notify your team

A notification is sent according to the set of alerting conditions. To configure notifications:

  1. Select users and/or services to send the notifications to. Note that you can use the @-notification feature in the message field.
  2. Enter a message for the API test. This field allows standard Markdown formatting. Notification messages include the message defined in this section and information about which assertion failed and why.
  3. Click Save to save your API test.

Notifications example:

Network timings

The Synthetics details page displays the following network timings:

TimingDescription
DNSTime spent resolving the DNS name of the last request.
ConnectTime spent establishing a connection to the server.
SSLTime 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.
DownloadTime spent downloading the response.

Response time is the sum of these network timings.

Further Reading