Слоты

Управление слотами осуществляется с помощью двух ресурсов:

  • /slots - ресурс для управления коллекцией слотов
  • /slots/:id - ресурс для управления конкретным слотом с идентификатом :id
Метод Ресурс Результат
POST /slots создать слот
GET /slots найти слоты
GET /slots/:id получить данные слота
POST /slots/:id изменить данные слота
DELETE /slots/:id удалить слот

Создание слота

Чтобы создать слот, необходимо выполнить запрос POST /slots с JSON-документом в теле вида:

Поле Описание Обязателен Разрешенные значения
size Id размера Да
Целое число
site Площадка Да
Hostname вида ‘example.com’
Длина: 3-100 символов.
“^[-\w\.]{3,100}$”
description Описание Нет
UTF8-текст.
Длина: 0-400 символов.
“^[\p{L}\p{P}\p{S}\p{N}\s]{0,10000}$”

Каждый слот имеет уникальный id, генерируемый сервером при создании. Ссылка на созданный слот возвращается сервером в заголовке Location.

Пример:

$ curl --request POST \
       --include \
       --user "admin:admin" \
       --header "Content-Type: application/json" \
       --data \
       '{
         "size":1,
         "site":"example.com",
         "description":"This is my slot"
        }' \
       --url http://api.example.com/slots

HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Tue, 12 Nov 2013 08:14:43 GMT
Content-Type: application/json
Content-Length: 69
Connection: keep-alive
Location: http://api.example.com/slots/1

{
  "id":1,
  "size":1,
  "site":"example.com",
  "description":"This is my slot",
  "shows_today":0,
  "ushows_today":0,
  "clicks_today":0,
  "uclicks_today":0,
  "ctr_today":0.0,
  "uctr_today":0.0,
  "shows_yesterday":0,
  "ushows_yesterday":0
  "clicks_yesterday":0,
  "uclicks_yesterday":0,
  "ctr_yesterday":0.0,
  "uctr_yesterday":0.0
}

Только пользователи с ролью publisher и администратор могут создавать слоты. Пользователь с ролью publisher может создавать слоты только в рамках площадок, которые принадлежат его организации.

Поиск слотов

Чтобы получить список слотов, необходимо выполнить запрос GET /slots.

Параметры запроса

site – площадка, к-й принадлежит слот

Пример:

$ curl --request GET \
       --include \
       --user "admin:admin" \
       --url http://api.example.com/slots

HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Tue, 12 Nov 2013 08:19:29 GMT
Content-Type: application/json
Content-Length: 83
Connection: keep-alive

{
  "results": [
    {
      "id":1,
      "size":1,
      "site":"example.com",
      "description":"This is my slot",
      "company":"example",
      "shows_today":0,
      "ushows_today":0,
      "clicks_today":0,
      "uclicks_today":0,
      "ctr_today":0.0,
      "uctr_today":0.0,
      "shows_yesterday":0,
      "ushows_yesterday":0
      "clicks_yesterday":0,
      "uclicks_yesterday":0,
      "ctr_yesterday":0.0,
      "uctr_yesterday":0.0
    }
  ],
  "total_count": 1
}

Любой пользователь может искать слоты.

Пользователь с ролью publisher или publisher получат только те слоты, которые принадлежат его организация.

Пользователь с ролью advertiser получит все слоты.

Пользователь с ролью administrator получит все слоты.

Получение данных слотов

Чтобы получить данные слотов, необходимо выполнить запрос GET /slots/:id.

Пример:

$ curl --request GET \
       --include \
       --user "admin:admin" \
       --url http://api.example.com/slots/1

HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Tue, 12 Nov 2013 08:20:53 GMT
Content-Type: application/json
Content-Length: 69
Connection: keep-alive

{
  "id":1,
  "size":1,
  "site":"example.com",
  "description":"This is my slot"
}

Изменение данных слотов

Чтобы изменить данные слота, необходимо выполнить запрос POST /slots/:id.

Формат документа для обновления данных слота идентичен формату документа для создания слота. Если поле не указано или содержит литерал null, значение поля не будет обновлено.

Пример:

$ curl --request POST \
       --include \
       --user "admin:admin" \
       --header "Content-Type: application/json" \
       --data \
       '{
          "description":"My new slot"
        }' \
       --url http://api.example.com/slots/1

HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Tue, 12 Nov 2013 08:24:58 GMT
Content-Type: application/json
Content-Length: 65
Connection: keep-alive

{
  "id":1,
  "size":1,
  "site":"example.com",
  "description":"My new slot"
}

Только пользователи с ролью publisher в соответствующей организации и администраторы могут изменять слоты.

Удаление слота

Чтобы удалить слот, необходимо выполнить запрос DELETE /slots/:id.

Пример:

$ curl --request DELETE \
       --include \
       --user "admin:admin" \
       --url http://api.example.com/slots/1

Server: nginx/1.4.3
Date: Tue, 12 Nov 2013 08:26:21 GMT
Content-Type: application/json
Content-Length: 0
Connection: keep-alive

Только пользователи с ролью publisher в соответствующей организации и администраторы могут удалять слоты.

Получении статистики

Для того чтобы получить подробную статистику показов/кликов для выбранного слота, необходмо выполнить запрос вида:

GET /slots/:id/stats/:action/:step

Где:

id - id слота

action - shows, ushows, clicks, uclicks

step - hour, day

Чтобы получить статистику из заданного временного интервала, укажите параметры from, to с временем в формате ISO8601.

Если параметр from не указан, то будет возвращеня статистика за 7 дней. Если параметр to не указан, то будет возвращена статистика до текущего времени.

В полях from и to следует указывать время в часовом поясе площадки, которой принадлежит слот.

Пример:

$ curl --request GET \
       --include \
       --user "admin:admin" \
       --url http://api.example.com/slots/1/stats/shows/hour

HTTP/1.1 200 OK
Server: nginx/1.6.0
Date: Wed, 23 Jul 2014 06:16:57 GMT
Content-Type: application/json
Content-Length: 21
Connection: keep-alive

{
  "2014-07-23T9": 4,
  "2014-07-23T10": 5,
  "2014-07-23T11": 5
}
$ curl --request GET \
       --include \
       --user "admin:admin" \
       --url http://api.example.com/slots/1/stats/ushows/day?from=2014-07-15&to=2014-07-16T10:00:00

HTTP/1.1 200 OK
Server: nginx/1.6.0
Date: Wed, 23 Jul 2014 06:16:57 GMT
Content-Type: application/json
Content-Length: 21
Connection: keep-alive

{
  "2014-07-15": 10,
  "2014-07-16": 10
}