API Documentation

Overview

The Recreativ API provides access to the Recreativ infrastructure through a standardized programming interface. Through the API Recreativ you can do the same thing that is available when using the Recreativ.com account, but using the programming language of your choice.

Recreativ API is a RESTful API based on HTTP requests and responses in XML or JSON (P) format. If you are familiar with the Twitter API, Amazon S3, del.icio.us, or another web service, you can easily get started with our API.

This version of the API uses a token mechanism for authorization. This means that all requests must be encrypted and sent via SSL / TLS to https: //. This also means that each request must be accompanied by a specially formed HTTP header, in which there will be an authorization key. You can find this key in your personal account on the profile page.

Code example

user@localhost:~$ curl 'https://recreativ.com/api/advertiser/campaigns?filter[id]=111,222' \
     -H 'Content-Type: application/json; charset=UTF-8' \
     -H 'Accept: application/json' \
     -H 'Auth-Token: eNldKDZHFuemaotqp6166WhZ0nximcHz'
     -v
> GET /api/advertiser/campaigns?filter[id]=111,222 HTTP/1.1
> User-Agent: curl/7.35.0
> Host: recreativ.com
> Content-Type: application/json; charset=UTF-8
> Accept: application/json
> Auth-Token: eNldKDZHFuemaotqp6166WhZ0nximcHz
> < HTTP/1.1 200 OK< Server: nginx< Date: Wed, 18 Feb 2015 15:34:24 GMT< Content-Type: application/json; charset=UTF-8< Transfer-Encoding: chunked< Connection: keep-alive<
[  
   {  
      "id":111,
      "title":"Первая кампания",
      "active":1,
      "maxclicks":0,
      "maxmoney":"0.0000",
      "isRetarget":0
   },
   {  
      "id":222,
      "title":"Вторая кампания",
      "active":1,
      "maxclicks":1000,
      "maxmoney":"25.0000",
      "isRetarget":0
   }
]

Need help?

If you have any questions, ask our support team by mail, skype or through the form on the site.

Entry points

The API is accessible through HTTP requests to a specific URL, which contains information about exactly what you want to do in the GET and POST variables. All endpoints are accessible only through encrypted HTTPS connection.

API response format

For data transfer XML and JSON are used. The choice of a specific format depends on the Accept header in the server request. To receive a response in JSON, the value of this header must contain the MIME type JSON - application / json, for XML - application / xml. All communication with the server occurs via the HTTPS.

Stable root endpoint of the latest version:

https://recreativ.com/api/

The response can be generated both in JSON format and in XML. This behavior depends on the passed Accept header, which should contain the type of response you want.

Authorization

Authorization takes place using a special key, the so-called access token, which should accompany each request to the server in the Auth-Token request header.

To connect the API, you must contact our support team, after which your personal key for authorization in the API will be available in the settings of your personal account.

Query restriction

The number of API requests per second is limited to 5 requests. If this number is exceeded, you will receive a server response with code 429.

This page describes the addresses of endpoints with the parameters that are used when creating the request.

User

Website

Block

Campaign

Ad

This page lists all the data structures that are used in the API responses.

User

Campaign Statistics

Campaign

Ad Stats

Ad

Category

Image

Website

Block

General information

The status of the request is indicated by the response code of the server with the corresponding status. If the error requires a more detailed description, the response body may contain a list with the `message` parameter. The value of which will be an extended description of the error.

Error example

Attempting to request a resource without the appropriate rights will result in the following error:

XML

<response>
   <name>Unauthorized</name>
   <message>You are requesting with an invalid credential.</message>
   <code>0</code> 
   <status>401</status>
</response> 
 

JSON

{
   "name": "Unauthorized",
   "message": "You are requesting with an invalid credential.",
   "code": 0,
   "status": 401
}
 

Status 200

The request was successfully processed by the server and no errors occurred.

Status 201

The resource was successfully created in response to the `POST` request. The `Location` header contains a URL pointing to the newly created resource.

Status 204

The request was processed successfully, and there is no content in the response (for the `DELETE` request, for example).

Status 304

The resource has not changed. You can use the cached version.

Status 400

Invalid request. It can be connected with various problems on the user side, such as incorrect JSON data in the request body, incorrect action parameters, etc.

Status 401

Authentication failed.

Status 403

An authenticated user is not allowed access to the specified API entry point.

Status 404

The requested resource does not exist.

Status 405

The method is not supported. See the list of supported HTTP methods in the `Allow` header.

Status 415

Unsupported data type. The wrong data type or version number is requested.

Status 422

Data verification failed (in response to a `POST` request, for example). For detailed error messages, see the response body.

Status 429

Too many requests. Request denied due to exceeding request frequency limits.

Status 500

Internal Server Error. A possible cause is errors in the program itself.