EXADS

API Overview

Table of Contents
1. API Overview
2. Versions
3. API Interface
4. HTTP Verbs
5. HTTP Headers
6. Returned Data - Standard Types
7. Errors
8. Pagination
9. Rate Limiting
10. PHP Code Examples
i. Login
ii. Authentication
iii. Collections
iv. Statistics
11. Changelog

2
EXADS API Overview

API Overview
This document presents a general overview of how to interact and use the EXADS Public API Version 1.

An interactive interface to the API, along with detailed request descriptions and responses, is available here.

A PDF version of this overview is available here.

A PHP Client is also available to expediate integration of the EXADS API into your application. The package can be
downloaded from GitHub.

API Overview 3
EXADS API Overview

Versions
The API version required should be specified in the URL of the request.

To specify the version required, place a 'v' followed by the version number itself e.g. v1. This should then be placed directly
proceeding the TLD, before the endpoint required.

A valid request to the API including the version number therefore would be:

https://api.exoclick.com/v1/login

Versions 4
EXADS API Overview

API Interface
The API Interface is a representation of the EXADS API designed to detail available requests, their associated parameters
and their expected responses.

All API requests are listed under their associated group.

In order to access restricted API requests, there must be an API Token set. To set a token, you must have a valid account
with the required username and password. Click on the Set API Token button on the top right of the screen and enter your
username and password. After you click the Login button, a login request will be made to the API to retrieve a valid token.
This token will then be used to validate all API requests you wish to make in that session.

To make a request to the API, click on a group. The group will expand to list the requests available. Click again on the
desired request. A panel will expand detailing the request details.

The Response body, if any, will be displayed first alongside the response Content-type.

The Request parameters, required and/or optional, are detailed next, along with the request Content-type, if required.

Expected Response Messages are then listed out.

To make the request, fill in the required parameters. If the request body is detailed, clicking on the body in the Model
window will pre-populate the parameter window with the body.

Once all required parameters have been set, clicking on the Try it Out button will execute the request.

Four panels will appear below the button. The first displays the full Request URL.

The second details the Response Body.

The third details the Response Code.

The fourth details the Response Headers.

API Interface 5
EXADS API Overview

HTTP Verbs
The following subset of HTTP verbs are supported. Please note that not all URLs will support all verbs. For information
what verbs to use for a particular resource see that resource's documentation.

Verb Uses

GET Fetches an object

POST Creates a new object

PUT Updates an existing object

DELETE Deletes an object

HTTP Verbs 6
EXADS API Overview

HTTP Headers
This section describes the HTTP headers the API will accept from any request.

Content-Type
All requests must contain a content-type HTTP Header.

Accepted Content-Types

Base Format Content-Types Notes

JSON application/json text/json is currently not an accepted content type

Content-Type Errors

Response
Notes
Code

The content type was understood but could not be decoded. More information will appear in the
400
response body

415 The content type is missing or is not supported

In cases where the content-type header has a problem then the response content-type will be the default format for the
API, currently application/json

The API currently does not adhere to the Accept-type HTTP Header, all responses are sent in the same content-type as the
received request provided the request's content-type was valid

Authorization
This header is optional and is used to provide authentication details to the API for the current user which will enable the
current user to access restricted API resources. Tokens can be obtained via the Login API. An example header is:

Authorization: Bearer 45267dbe480c8c7d799c62ccad92cb44f67ab086

The Authorization header accepts a string that is built from two parts, seperated by a single space. The first part is the
token type, the second is the access token itself.

Authorization Errors

Response Code Notes

400 A malformed authorization header was provided

401 The authorization header is missing or the token was invalid or expired

Choosing an authorisation token type On any failure the response headers will contain a WWW-Authenticate header
which will indicate the token type that is required for access.

HTTP Headers 7
EXADS API Overview

Returned Data - Standard Types

Dates/Time

For the date format and time format we will use ISO 8601 standard. For dates only we will use the short variant ISO 8601:
YYYY-MM-DD

Returned Data - Standard Types 8

EXADS API Overview

Errors
All errors will return the most specific, appropriate HTTP response code from the following table:

Return Codes

Code Error Description

A malformed request was received from the client. This is the most generic
400 Bad Request
response given by the API

401 Unauthorized You are not authorized and cannot access the requested resource

403 Forbidden You do not have permission to access the requested resource

404 Not Found The requested resource cannot be found. It may become available later

Method Not
405 An unsupported HTTP method was used for the requested resource
Allowed

406 Not Acceptable The Accept or Accept-Encoding type requested by the client is not available

The request cannot be completed because there is a conflict with the existing
409 Conflict
resource

410 Gone The requested resource is no longer available and never will be in future

411 Length Required The requested resource expects a Content-Length to be supplied by the client

Request Entity The request body supplied by the client was too large, the resource refuses to
413
Too Large process it

Unsupported
415 An incorrect (or no) Content-Type has been supplied by the client
Media Type

Unprocessable The request is not malformed and the media type is acceptable but the resource
422
Entity cannot process the request

Too many The rate limit has been reached. Please see Rate Limiting section for more
429
requests information

Internal Server The server could not process your request due to an unexpected internal server
500
Error error

501 Not Implemented The requested resource has not been implemented

Service
503 The requested service is temporarily not available
Unavailable

Standard Response Format

All errors will have a standard response body with two fields, code and message. More fields can be used but they are
optional.

Examples

This is the simplest form of an error's return body, clients can rely on these fields being present in every error.

Error Responses - Example 1 (Baseline)

Errors 9
EXADS API Overview

{
"code": 429,
"message": "You have exceeded your number of requests. Please try again later"
}

The following example has, in addition to the standard fields, for errors associated with this specific request.

Error Responses - Example 2 (More Complex)

{
"code": 422,
"message": "Unprocessable entity",
"cause": "Validation failed",
"errors": [
{
"resource": "Issue",
"field": "title",
"code": "missing_field"
},
...
]
}

Errors 10
EXADS API Overview

Pagination
Requests that return multiple items can be paginated. The standard way of performing pagination is with GET parameters -
limit and offset. Page numbering is 1-based.

Parameter Description Notes

limit The number of records to return in this request Default is 50. Minimum value is 1

offset The position to retrieve the records from. Default is 0. Minumum value is 0

Examples

Pagination - Example 1

$ curl -i https://api.exoclick.com/v1/statistics/advertiser/sites?limit=5&offset=40

Pagination 11
EXADS API Overview

Rate Limiting
The API is rate-limited to 150000 requests every 900 seconds. All requests count towards the total. Every request
processed by the API returns rate limiting information in the HTTP headers.

Examples

Rate Limiting - Example 1

$ curl -i https://api.exoclick.com/v1/statistics/advertiser/date

{
"HTTP/1.1": "200 OK",
"Date": "Fri, 24 Oct 2014 14:57:32 GMT",
"Content-Type": "application/json",
"Transfer-Encoding": "chunked",
"X-Rate-Limit-Limit": 150000,
"X-Rate-Limit-Remaining": 149994,
"X-Rate-Limit-Reset": 27
}

When the rate limit is exceeded a 429 Too Many Requests HTTP error will be thrown by any subsequent requests until the
rate limit is reset. As with a normal request the rate limiting information will be available in the HTTP headers.

Rate Limiting - Example 2 (Limit Exceeded)

$ curl -i https://api.exoclick.com/v1/statistics/advertiser/date

{
"HTTP/1.1": "429 Too Many Requests",
"Date": "Fri, 24 Oct 2014 15:04:35 GMT",
"Content-Type": "application/json",
"Transfer-Encoding": "chunked",
"X-Rate-Limit-Limit": 150000,
"X-Rate-Limit-Remaining": 0,
"X-Rate-Limit-Reset": 12
}

Rate Limiting 12
EXADS API Overview

PHP Code Examples

The code samples in this section all use the following classes.

The Request class uses cURL to make the requests to the API.

The Response class contains the API response and returned status code info.

class Request {

/**
* @var resource
*/
protected $_request;

/**
* @var integer
*/
protected $_method;

/**
* @var string
*/
protected $_url;

/**
* @var array
*/
protected $_headers = array(
'Content-type: application/json'
);

/**
* @var string|array
*/
protected $_params;

/**
* @var object Response
*/
protected $_reponse;

/**
* Constructor
*
* @param string $url
* @param string $method
* @param array $params
*/
public function __construct($url, $method, $params = array()) {

$this->_url = $url;

// Set the method

$this->_method = $method;

// Set the params

$this->_params = $params;
}

/**
* Determine the Request method
*
* @param string $method
*/
private function setMethod() {

switch($this->_method) {
case 'GET':
break;

PHP Code Examples 13

EXADS API Overview

case 'POST':
curl_setopt($this->_request, CURLOPT_POST, 1);
break;
case 'PUT':
curl_setopt($this->_request, CURLOPT_CUSTOMREQUEST, 'PUT');
break;
case 'DELETE':
curl_setopt($this->_request, CURLOPT_CUSTOMREQUEST, 'DELETE');
break;
}
}

/**
* Add authorization header
*
* @param string $type
* @param string $token
*/
public function setAuthorizationHeader($type, $token) {

$authorization = $type . ' ' . $token;

$this->_headers[] = 'Authorization: ' . $authorization;

}

/**
* Add body to request
*/
private function addBody() {

if($this->_method != 'GET' && empty($this->_params) == false) {

if(is_array($this->_params)) {
// JSON Encode the array
$this->_params = json_encode($this->_params);
}

curl_setopt($this->_request, CURLOPT_POSTFIELDS, $this->_params);

// Add a content-length header

$this->_headers[] = 'Content-length: ' . strlen($this->_params);
}
}

/**
* Add a query string to the request
*/
private function addQueryString() {

if($this->_method == 'GET' && is_array($this->_params) && count($this->_params) > 0) {

$query_string = '?';

foreach($this->_params as $param => $value) {

$query_string = $query_string . $param . '=' . $value . '&';

}

trim($query_string, '&');

$this->_url = $this->_url . $query_string;

}
else {

if(is_array($this->_params) && count($this->_params) > 0 && strpos($this->_url, '{') !== false) {

// Pattern match params against the url
foreach($this->_params as $param => $value) {
$this->_url = preg_replace('/{' . $param . '}/', $value, $this->_url);
}
}
}
}

/**
* Send the request
*/
public function send() {

PHP Code Examples 14

EXADS API Overview

// Initialise cUrl request

$this->_request = curl_init();

// Return the response as a string

curl_setopt($this->_request, CURLOPT_RETURNTRANSFER, 1);

// Add a query string

$this->addQueryString();

// Set the URL

curl_setopt($this->_request, CURLOPT_URL, $this->_url);

// Set request method

$this->setMethod();

// Add a body
$this->addBody();

if(empty($this->_headers) == false) {
// Set the headers
curl_setopt($this->_request, CURLOPT_HTTPHEADER, $this->_headers);
}

// Disable SSL checks

curl_setopt($this->_request, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($this->_request, CURLOPT_SSL_VERIFYHOST, false);

// Send the request and store the body

$this->_response = new Response(curl_exec($this->_request));

// Set the status code

$this->_response->setStatusCode(curl_getinfo($this->_request, CURLINFO_HTTP_CODE));

// Close the connection

curl_close($this->_request);
}

/**
* Get the response
*
* @return object
*/
public function getResponse() {

return $this->_response;
}
}

class Response {

/**
* @var array
*/
protected $_reason_phrases = array(
//Informational 1xx
100 => "Continue",
101 => "Switching Protocols",

// Successful 2xx
200 => "OK",
201 => "Created",
202 => "Accepted",
203 => "Non-Authoritative Information",
204 => "No Content",
205 => "Reset Content",
206 => "Partial Content",

// Redirection 3xx
300 => "Multiple Choices",
301 => "Moved Permanently",
302 => "Found",
303 => "See Other",
304 => "Not Modified",
305 => "Use Proxy",
306 => "(Unused)",
307 => "Temporary Redirect",

// Client Error 4xx

PHP Code Examples 15

EXADS API Overview

400 => "Bad Request",

401 => "Unauthorized",
402 => "Payment Required",
403 => "Forbidden",
404 => "Not Found",
405 => "Method Not Allowed",
406 => "Not Acceptable",
407 => "Proxy Authentication Required",
408 => "Request Timeout",
409 => "Conflict",
410 => "Gone",
411 => "Length Required",
412 => "Precondition Failed",
413 => "Request Entity Too Large",
414 => "Request-URI Too Long",
415 => "Unsupported Media Type",
416 => "Requested Range Not Satisfiable",
417 => "Expectation Failed",

// Server Error 5xx

500 => "Internal Server Error",
501 => "Not Implemented",
502 => "Bad Gateway",
503 => "Service Unavailable",
504 => "Gateway Timeout",
505 => "HTTP Version Not Supported"
);

/**
* @var integer
*/
protected $_status_code;

/**
* @var string
*/
protected $_body;

/**
* Constructor
*
* @param string $body
*/
public function __construct($body) {

$this->_body = $body;
}

/**
* Constructor
*
* @param string $status_code
*/
public function setStatusCode($status_code) {

$this->_status_code = $status_code;
}

/**
* Get status code
*
* @return integer
*/
public function getStatusCode() {

return $this->_status_code;
}

/**
* Get body
*
* @return string
*/
public function getBody() {

return $this->_body;
}

PHP Code Examples 16

EXADS API Overview

/**
* Get body JSON Decoded
*
* @return object|null
*/
public function getBodyDecoded() {

return json_decode($this->_body);
}

/**
* Get reason phrase
*
* @return string|boolean
*/
public function getReasonPhrase() {

if(array_key_exists($this->_status_code, $this->_reason_phrases)) {

return $this->_reason_phrases[$this->_status_code];
}
else {

return false;
}
}
}

PHP Code Examples 17

EXADS API Overview

Login
The following is an example of a request to the login route of the API.

<?php

// Include Request and Response classes

$url = 'https://api.exoclick.com/v1/login';

$params = array(
'username' => 'sample_username',
'password' => 'sample_password'
);

// Create a new Request object

$request = new Request($url, 'POST', $params);

// Send the request

$request->send();

// Get the Response object

$response = $request->getResponse();

if($response->getStatusCode() == 200) {

print_r($response->getBodyDecoded());
}
else {

echo $response->getStatusCode() . PHP_EOL;

echo $response->getReasonPhrase() . PHP_EOL;
echo $response->getBody() . PHP_EOL;
}
?>

Login 18
EXADS API Overview

Authentication
Each request to user related content requires an Authorization header to be set, with the value containing the token type
and token received from the API Login request.

A valid /login request to the API will return the following json payload.

{
"token": "",
"type": "",
"expires_in": 0
}

The token should be included in all subsequent user related content requests to the API.

The type is to be prepended to the the token, separated by a single space.

Bearer 4e63518d383d8fcaefb516fe708b893727463031

The expires_in is the time in seconds that the token will be valid for. When this time expires, a new token will need to be
attained via the /login request.

Example of Getting and Setting Authorization Header

<?php

// Include Request and Response classes

// Login
$url = 'https://api.exoclick.com/v1/login';

$params = array(
'username' => 'sample_username',
'password' => 'sample_password'
);

// Create a new Request object

$request = new Request($url, 'POST', $params);

// Send the request

$request->send();

// Get the Response object

$response = $request->getResponse();

if($response->getStatusCode() == 200) {

// Retrieve the token details

$token = $response->getBodyDecoded();

// Get Campaigns
$url = 'https://api.exoclick.com/v1/campaigns';

// Create a new Request object

$request = new Request($url, 'GET');

// Set the Authorization Header

$request->setAuthorizationHeader($token->type, $token->token);

// Send the request

$request->send();

Authentication 19
EXADS API Overview

// Get the Response object

$response = $request->getResponse();

if($response->getStatusCode() == 200) {

// Retrieve the campaigns

$campaigns = $response->getBodyDecoded();

foreach($campaigns->result as $campaign) {
// Display the campaign names
echo $campaign->name . PHP_EOL;
}
}
else {
// Campaigns request error
echo $response->getStatusCode() . PHP_EOL;
echo $response->getReasonPhrase() . PHP_EOL;
echo $response->getBody();
}
}
else {
// Invalid Login
echo $response->getStatusCode() . PHP_EOL;
echo $response->getReasonPhrase() . PHP_EOL;
echo $response->getBody();
}
?>

Authentication 20
EXADS API Overview

Collections Request
The following is an example of a request to get the Browsers collection.

<?php

// Include Request and Response classes

$url = 'https://api.exoclick.com/v1/collections/browsers';

// Create a new Request object

$request = new Request($url, 'GET');

// Set the Authorization Header retrieved from earlier Login request

$request->setAuthorizationHeader($token->type, $token->token);

// Send the request

$request->send();

// Get the Response object

$response = $request->getResponse();

if($response->getStatusCode() == 200) {

$browsers = $response->getBodyDecoded();

foreach($browsers as $browser) {

echo $browser->id . ': ' . $browser->name . PHP_EOL;

}
}
else {
// Collection not found
echo $response->getStatusCode() . PHP_EOL;
echo $response->getReasonPhrase() . PHP_EOL;
echo $response->getBody();
}
?>

Collections 21
EXADS API Overview

Statistics Request
The following is an example of a request to statistics/advertiser/date .

<?php

// Include Request and Response classes

$url = 'https://api.exoclick.com/v1/statistics/advertiser/date';

// Specify the campaign id

$params = array(
'campaignid' => 1234
);

$request = new Request($url, 'GET', $params);

// Set the Authorization Header, retrieved from earlier Login request

$request->setAuthorizationHeader($token->type, $token->token);

// Send the request

$request->send();

// Get the response object

$response = $request->getResponse();

if($response->getStatusCode() == 200) {

$statistics = $response->getBodyDecoded();

foreach($statistics->result as $statistic) {

echo $statistic->ddate . ': ' . $statistic->value . PHP_EOL;

}
}
else {
// Campaign statistics not found
echo $response->getStatusCode() . PHP_EOL;
echo $response->getReasonPhrase() . PHP_EOL;
echo $response->getBody();
}
?>

Statistics 22
EXADS API Overview

Changelog

Version 1.0.1
Bug fix to campaigns:
active field removed
status field now
-1 = deleted
0 = paused
1 = running

Version 1.0
Endpoints available in API V1
campaigns
GET - /campaigns
GET - /campaigns/{campaignid}
PUT - /campaigns/{campaignid}/copy
PUT - /campaigns/{campaignid}/delete
PUT - /campaigns/{campaignid}/pause
PUT - /campaigns/{campaignid}/play
PUT - /campaigns/{campaignid}/restore
collections
GET - /collections
GET - /collections/browsers
GET - /collections/carriers
GET - /collections/categories
GET - /collections/countries
GET - /collections/devices
GET - /collections/languages
GET - /collections/operating-systems
login
POST - /login
payments
GET - /payments/advertiser
GET - /payments/publisher
sites
GET - /sites
statistics
GET - /statistics/advertiser/browser
GET - /statistics/advertiser/carrier
GET - /statistics/advertiser/category
GET - /statistics/advertiser/country
GET - /statistics/advertiser/date
GET - /statistics/advertiser/device
GET - /statistics/advertiser/hour
GET - /statistics/advertiser/language
GET - /statistics/advertiser/os
GET - /statistics/advertiser/site

Changelog 23
EXADS API Overview

GET - /statistics/advertiser/variation
GET - /statistics/publisher/browser
GET - /statistics/publisher/carrier
GET - /statistics/publisher/category
GET - /statistics/publisher/country
GET - /statistics/publisher/date
GET - /statistics/publisher/device
GET - /statistics/publisher/hour
GET - /statistics/publisher/os
GET - /statistics/publisher/site
GET - /statistics/publisher/sub
GET - /statistics/publisher/zone
user
GET - /user
PUT - /user
POST - /user/changepassword
zones
GET - /zones

Changelog 24