Protection API

The Protection API provides a decision to allow or block any HTTP request based on its properties.

Validation requests should be sent to the Protection API by modules installed on a component of your backend infrastructure (CDN, load balancer, application server, etc).

API responses

API calls return HTTP status codes and headers that you can use inside your module or application.

API status codes

Module behavior must change depending of the following API response code:

📘

Handling unsupported HTTP status codes

Status codes that are not listed in the table above should be ignored by the module and the request should be let through.

📘

Validating the X-DataDomeResponse header

The module must validate that the HTTP status code returned by the API has the same value as the X-DataDomeResponse header. If not, the module must ignore it and allow the request as if it received a 200 response.

Handling API response headers

The module must merge certain headers coming from the API depending on the decision it made.

Headers to add to the client request and response

• The API response will include a X-DataDome-request-headers header that lists the names of the headers to pick up from itself and add to the client request before it reaches the origin.
• If the request should be blocked, it will also include a X-DataDome-headers header that lists the names of the headers to pick up from itself and add to the response that will be sent to the client.

🚧

Some headers must not be sent back to the client

Clients like web browsers, web views or mobile applications should never receive the following headers:

• X-DataDome-request-headers
• Any header that was listed by X-DataDome-request-headers
• X-DataDome-headers

• Here is an example of response headers sent by the API:

X-DataDome-request-headers: X-DataDome-botname X-DataDome-botfamily X-DataDome-isbot
X-DataDome-botname: Crawler fake Google
X-DataDome-botfamily: bad_bot
X-DataDome-isbot: 1
X-DataDome-headers: Set-Cookie Pragma X-DataDome Cache-Control
Set-Cookie: datadome=some-value; Domain=domain.com; Path=/; Expires=Wed, 13 Jan 2021 22:23:01 GMT;
Pragma: no-cache
X-DataDome: protected
Cache-Control: no-cache
X-DataDomeResponse: 403

• Here is what the module should add to the client request:

X-DataDome-botname: Crawler fake Google
X-DataDome-botfamily: bad_bot
X-DataDome-isbot: 1

• Here is what the module should add to the client response:

Set-Cookie: datadome=some-value; Domain=domain.com; Path=/; Expires=Wed, 13 Jan 2021 22:23:01 GMT;
Pragma: no-cache
X-DataDome: protected
Cache-Control: no-cache

📘

JSON responses and the X-DD-B header

When the API blocks a request that had a Content-Type: application/json header, then it will reply with a JSON response too unless the targeted endpoint was configured to return an HTML response on your dashboard.

The API will always include an X-DD-B header to JSON responses, which will be listed by X-DataDome-headers, meaning it must be added to client responses.

Size limits for payload fields

❗️

Total size limit (24 kB)

API servers won't accept incoming request payloads that are larger than 24 kB.
Each field must be truncated according to the limits defined in the table below.

❗️

Truncation order

Fields with an asterisk (*) should be truncated from the end.