* Please note that all API requests must be performed via HTTPS.
The main provisions of REST API
REST API allows you to integrate external applications with Adskeeper online
advertising system.
API provides the ability to retrieve, add, and modify the data. Practically each object in Adskeeper (whether it's a client, an advertising company, a teaser, etc.) can be controlled by API. Adskeeper REST API Request is an HTTP request which with the help of the ways in the URL the object to perform the action is specified, and with the help of parameters the necessary data is passed. Adskeeper API is a "RESTful Web API". The API uses the following REST commands:
- GET
- PUT
- PATCH
- POST
- DELETE
The query parameters are case sensitive.
These commands correspond to certain actions within the Adskeeper system. Get an item or a collection of items (for example, a list of advertising campaigns):
| Command | Action | Description |
| POST | Create | Creates a new element (eg, a teaser) |
| GET | Get (read) | Retrieve an element or a collection of elements |
| PUT | Update | Recreate an existing element or a collection of elements |
| PATCH | Change | Change certain properties of an element |
| DELETE | Delete | Delete an item or collection of items (eg, move a teaser to recycle bin) |
| Important! POST and PUT are not interchangeable. Each of the commands fulfills its specific function. | ||
In general, the query looks like this:
https://api.adskeeper.co.uk/v1/module/controller/action?parameter_1=value_of_parameter_1¶meter_2=value_of_parameter_2¶meter_3=value_of_parameter_3
Identification
For identification the Adskeeper REST API uses a unique token consisting of 32 characters which is passed in the client’s request Authorization header. To obtain a valid token client should use a special API function.
| Every request sent to the Adskeeper REST API must contain the API token |
REST API answer
In response to a request to the REST API server always returns the HTTP response with a status code, depending on the result of the query.
| Answer code | Description |
| 200 OK | The query has been successfully processed |
| 400 Bad Request | Syntax error |
| 404 Not Found | Item or page not found |
Format of the returned data
The returned data can be formatted as JSON, or XML. The default format is JSON. The request header is used to specify the format in which the data is
returned. The client sends an Accept header, which indicates desired response format:
Accept: application / xml
or
Accept: application / json
Description of the response format is sent in the response header Content Type. The data returned is the answer is a JSON string, which generally looks as follows:
{
"element_1":"value_of_element_1",
"element_2":"value_of_element_2",
"element_3":{
"property_1_of_element_3":"value_of_property_1_of_element_3",
"property_2_of_element_3":[
"value_1_of_property_2_of_element_3",
"value_2_of_property_2_of_element_3"
]
}
. . . .
}
If an error has occurred during the execution of the query the description corresponding to the error is returned, such as:
{ "errors": [ "[_error_description_]" ] }
Working with clients
Getting the current client's token
| Method | URL |
| POST | api.adskeeper.co.uk/v1/auth/token |
Transferred parameters:
| Parameter | Value |
| E-mail of the client, specified at registration in Adskeeper system | |
| password | Password of the client, received during registration in Adskeeper system |
Returns an answer:
{
"token":"_current_token_",
"refreshToken":"_token_for_refresh_"
"idAuth":"_client_api_id_"
}
_current_token_ is used to identify the client;
_token_for_refresh_ will be used in future versions to update an overdue current token.
Working with widgets
Custom reports
| Method | GET |
| URL | api.adskeeper.co.uk/v1/publishers/{authId}/widget-custom-report |
| Headers |
Accept: application/json Authorization: Bearer {token} |
Transferred parameters (required parameters are marked with asterisk *):
| Parameter | Value |
| dateInterval* |
Interval of time you need to get a statistics. Valid values:
In addition, you can transfer the hour intervals:
|
| siteId* | Client's site ID |
| dimensions* |
list of fields to group. It can take multiple values separated by a comma. Valid values are:
|
| metrics* |
list of fields for extracting indicators. It can take multiple values separated by a comma. Valid values are:
|
| page | page number with statistics |
| perPage | records number per page. Default 1000, maximum 100 000, minimum 1 |
| widgetId | composite widget ID |
| deviceType | device type (desktop, tablet, mobile) |
| countryIso | country code (alpha2) |
| sortBy | sort by field (can take one of the transmitted values dimensions or metrics), if not passed, sorts by the first parameter from dimensions |
| sortMethod | direction of sorting (asc, desc), if not sent then applied ASC direction |
| timeZone | Timeshift of statistics. Available list of timeZones here ( TZ ). If the parameter not passed timeZone will be set to America/Los_Angeles |