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

Additional features to support

Session by header

Here are the prerequisites to support the session by header feature available on the JS Tag.

• If an incoming HTTP request includes a X-DataDome-ClientID header, its value should be picked for the ClientID field instead of the datadome cookie.

When session by header is enabled on the JS Tag, it will expect to get the new cookie value from the X-Set-Cookie header instead of the standard Set-Cookie header.

• To enable that response header, add the following header on the HTTP request that will be sent to DataDome's Protection API: X-DataDome-X-Set-Cookie: true

Here is an example of implementation in Lua:

if request_headers['x-datadome-clientid'] ~= nil then  
   body['ClientID'] = request_headers['x-datadome-clientid']  
   datadomeHeaders["X-DataDome-X-Set-Cookie"] = "true"  
else  
   body['ClientID'] = clientId  
end

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.

❗️

Empty header values

If a header value is empty, the corresponding field shouldn't be sent with the payload.