Handle API Response
API calls return HTTP codes and Headers that you can use inside your module or application.
API Response Code
Module behavior must change depending of the following API response code:
API Response | Meaning | Action to Take |
---|---|---|
400 | The request has not been applied because it lacks valid authentication credentials | Check that you have set the correct API Key. Contact us if the problem persists. |
401/403 | The current hit should be blocked according to rules | The module should stop processing the hit and output the HTML code returned by the API in the body section. |
301/302 | The current hit should be redirected to a specific page | The module should redirect to the “Location” field found in API Response header. |
200 | The hit should be allowed | The module should let the application proceed. |
Any other response code should be ignored.
The module must check if the HTTP response code has the same value as the X-DataDomeResponse
header. If not, the module must act like it is a 200
code.
Each DataDome request should also have X-DataDome
header with value protected
that can be sent in different cases, for example as Protected
.
All these headers are sent via server-side integration like http
, http_raw
, spoa
etc.
When APIServer blocks a request and the response has content-type application/json
that is forced by segment or accept-headers, it also adds X-DD-B
headers to both client-side and server-side integrations.
API Response Header
The module must parse the headers:
- “X-DataDome-request-headers”, which contain the name of the headers that must be added to the request.
- “X-DataDome-headers”, which contain the name of the headers that must be added to the final client response.
API Server response headers example:
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
Module should add the below to client request:
X-DataDome-botname: Crawler fake Google
X-DataDome-botfamily: bad_bot
X-DataDome-isbot: 1
Module should add to the below to 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
API Field Size
API servers won't accept incoming body requests that are larger than 24kb.
Each field must be truncated by the module according to the below rules:
Headers with the asterisk (*) should be truncated from the end.
Fields | Limit (in bytes) |
---|---|
Key, APIConnectionState, AuthorizationLen, CookiesLen, IP, Method, ModuleVersion, Port, PostParamLen, Protocol, RequestModuleName, TimeRequest | Unlimited |
Sec-CH-Device-Memory, Sec-CH-UA-Mobile, Sec-Fetch-User | 8 |
Sec-CH-UA-Arch | 16 |
Sec-CH-UA-Platform, Sec-Fetch-Dest, Sec-Fetch-Mode | 32 |
Sec-Fetch-Site | 64 |
AcceptCharset, AcceptEncoding, CacheControl, ClientID, Connection, Pragma, Sec-CH-UA, Sec-CH-UA-Model, TrueClientIP, X-Real-IP, X-Requested-With | 128 |
AcceptLanguage, Sec-CH-UA-Full-Version-List, Via | 256 |
Accept, HeadersList, Host, Origin, ServerHostname, ServerName, XForwardedForIP* | 512 |
UserAgent | 768 |
Referer | 1024 |
Request | 2048 |