Площадки

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

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

Создание площадки

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

Поле Описание Обязателен Разрешенные значения
id Id площадки Да
Строка содержащая латинские символы,
цифры, ‘_’, ‘-‘, ‘.’
Длина: 3-100 символов.
“^[-\w\.]{3,100}$”
payment_type Тип расчетов Да
money, account
view_rate Ставка за 1000 показов Нет
Число с плавающей точкой
click_rate Ставка за 1 клик Нет
Число с плавающей точкой
company Id организации Да
Id существующей организации
“^[-\w]{3,20}$”
tz Таймзона Нет
Строка в формате ±HH:MM
description Описание Нет
UTF8-текст.
Длина: 0-400 символов.
“^[\p{L}\p{P}\p{S}\p{N}\s]{0,10000}$”

Пример:

$ curl --request POST \
       --include \
       --user "admin:admin" \
       --header "Content-Type: application/json" \
       --data \
       '{
          "id":"example.com",
          "payment_type":"money",
          "view_rate":1,
          "click_rate":1.5,
          "company":"example",
          "description":"This is your site"
        }' \
       --url http://api.example.com/sites

HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Tue, 12 Nov 2013 07:58:01 GMT
Content-Type: application/json
Content-Length: 71
Connection: keep-alive
Location: http://api.example.com/sites/example.com

{
  "id":"example.com",
  "payment_type":"money",
  "view_rate":1,
  "click_rate":1.5,
  "company":"example",
  "description":"This is your site",
  "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
}

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

Поиск площадок

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

Пример:

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

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

{
  "results": [
    {
      "id":"example.com",
      "payment_type":"money",
      "view_rate":1,
      "click_rate":1.5,
      "company":"example",
      "description":"This is your site",
      "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_guest получат только те площадки той же организации, сотрудником которой они являются.

Пользователь с ролью advertiser получит все площадки с полями id, description.

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

Получение данных площадки

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

Пример:

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

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

{
  "id":"example.com",
  "payment_type":"money",
  "view_rate":1,
  "click_rate":1.5,
  "company":"example",
  "description":"This is your site",
  "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
}

Изменение данных площадки

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

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

Пример:

$ curl --request POST \
       --include \
       --user "admin:admin" \
       --header "Content-Type: application/json" \
       --data \
       '{
          "description":"Example Inc."
        }' \
       --url http://api.example.com/sites/example.com

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

{
  "id":"example.com",
  "payment_type":"money",
  "view_rate":1,
  "click_rate":1.5,
  "company":"example",
  "description":"Example Inc.",
  "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 в той же организации и администраторы могут изменять данные площадки.

Удаление площадки

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

Пример:

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

HTTP/1.1 204 No Content
Server: nginx/1.4.3
Date: Tue, 12 Nov 2013 08:06:51 GMT
Content-Type: application/json
Content-Length: 0
Connection: keep-alive

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

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

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

GET /sites/: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/sites/example.com/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/sites/example.com/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
}