API tests are HTTP requests (GET, POST, PUT, etc.) executed by Datadog to your web properties or application endpoints at configurable periodic intervals from multiple locations around the world. 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.
Define the request you want to be executed by Datadog:
URL to query. Available
Optionally, click on Advanced options to enrich your request with custom request headers, authentication credentials, body content, or cookies.
Name your API test.
Optionally, add tags to filter your API test in the Synthetics page.
Pick locations to run the test from. Available locations are:
Choose a check frequency between “1 run per minute” and “1 run per week”.
Finish by clicking on Test URL to try out the request configuration. You should see a response preview show up in the right side of your screen.
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, a comparator, and a value.
If you define an assertion on the content of
Headers, you must define the headers name and the associated value.
Click on Add new assertion to add up to 10 assertions for your API test.
Note: If you clicked on Test URL, then the basic assertions are automatically filled:
Use the Test URL response to quickly add status code, response time or headers from the test response as one of the API test assertions:
A notification is sent if at least one of the assertion fails. To configure notifications:
@-notificationfeature in the message field.
The Synthetics details page displays the following network timings:
|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.
A check is considered
FAILED if it doesn’t satisfy the assertions configured for this check, or if the request failed for another reason. These reasons include:
|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 below for more detailed explanations.|
|TIMEOUT||The request couldn’t be completed in a reasonable time.|
|CERT_CHAIN_TOO_LONG||The certificate chain length is greater than the supplied maximum depth.|
|CERT_HAS_EXPIRED||The certificate is expired.|
|CERT_NOT_YET_VALID||The certificate is not valid until a future date.|
|CERT_REJECTED||The root CA is marked to reject the purpose specified.|
|CERT_REVOKED||The certificate was revoked by the issuer.|
|CERT_UNTRUSTED||The root CA is not marked as trusted for its intended purpose.|
|CERT_SIGNATURE_FAILURE||The signature of the certificate is not valid.|
|CRL_HAS_EXPIRED||The certificate revocation list (CRL) has expired.|
|CRL_NOT_YET_VALID||The certificate revocation list (CRL) is not valid until a future date.|
|CRL_SIGNATURE_FAILURE||The CRL signature of the certificate is not valid.|
|DEPTH_ZERO_SELF_SIGNED_CERT||The passed certificate is self-signed and the same certificate cannot be found in the list of trusted certificates.|
|ERROR_IN_CERT_NOT_AFTER_FIELD||There is a format error in the notAfter field in the certificate.|
|ERROR_IN_CERT_NOT_BEFORE_FIELD||There is a format error in the notBefore field in the certificate.|
|ERROR_IN_CRL_LAST_UPDATE_FIELD||The CRL lastUpdate field contains an invalid time.|
|ERROR_IN_CRL_NEXT_UPDATE_FIELD||The CRL nextUpdate field contains an invalid time.|
|INVALID_CA||A CA certificate is not valid because it is not a CA or its extensions are not consistent with the intended purpose.|
|INVALID_PURPOSE||The certificate that was provided cannot be used for its intended purpose.|
|OUT_OF_MEM||An error occurred while allocating memory.|
|PATH_LENGTH_EXCEEDED||The basicConstraints pathlength parameter was exceeded.|
|SELF_SIGNED_CERT_IN_CHAIN||A self-signed certificate exists in the certificate chain. The certificate chain can be built using the untrusted certificates, but the root CA cannot be found locally.|
|UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY||The public key in the certificate cannot be read.|
|UNABLE_TO_DECRYPT_CERT_SIGNATURE||Unable to decrypt the signature of the certificate.|
|UNABLE_TO_DECRYPT_CRL_SIGNATURE||The CRL signature cannot be decrypted. (The actual signature value cannot be determined.)|
|UNABLE_TO_GET_CRL||The certificate revocation list (CRL) is not found.|
|UNABLE_TO_GET_ISSUER_CERT||Unable to find the certificate for one of the certificate authorities (CAs) in the signing hierarchy, and that CA is not trusted by the local application.|
|UNABLE_TO_GET_ISSUER_CERT_LOCALLY||The issuer certificate of a locally found certificate is not found. This usually means that the list of trusted certificates is not complete.|
|UNABLE_TO_VERIFY_LEAF_SIGNATURE||No signatures are verified because the certificate chain contains only one certificate, which is not self-signed, and the issuer is not trusted.|