REST API Lentainform

Основные положения REST API

REST API lentainform  позволяет  интегрировать внешние приложения с системой  интернет-рекламы lentainform.API дает возможность извлекать, добавлять и изменять данные. Практически   каждым объектом в lentainform (будь то клиент, рекламная компания, тизер и т.д.) можно  управлять с помощью API.Запрос  lentainform REST API – это   HTTP запрос, в котором, с помощью  путей  в URL  задается объект для выполнения действия, а с помощью параметров передаются необходимые данные. lentainform API является «RESTful Web API». Параметры запросов являются регистрозависимыми. API использует  следующие команды REST:

  • GET
  • PUT
  • PATCH
  • POST
  • DELETE

Эти команды соответствуют определенным действия внутри системы lentainform.

КомандаДействиеОписание
POSTСоздатьСоздание новый элемента (например, тизера)
GETПолучить (чтение)Получить элемент или коллекцию  элементов (например, список рекламных кампаний)
PUTОбновитьПересоздать существующий элемент или коллекцию элементов
PATCHИзменитьИзменить определенные свойства элемента
DELETEУдалятьУдалить элемент или коллекцию элементов (например, переместить тизер в корзину)
Важно! POST и PUT не являются взаимозаменяемыми. Каждая из команд выполняет свою определенную функцию.
В общем виде запрос выглядит как http://api.lentainform.com/v1/модуль/контроллер/действие?token= _токен_клиента_&параметр_1=значение_параметра_1& параметр_2=значение_параметра_2&параметр_3=значение_параметра_3….

Идентификация

Для идентификации в REST API lentainform используется уникальный токен, состоящий из 32 символов и передаваемый в запросе клиента.Для получения действующего токена  клиент должен воспользоваться специальной функцией API

Каждый запрос, отправленный к REST API lentainform обязательно  должен содержать токен API.

Ответ REST API lentainform

В ответ на запрос к REST API сервер  всегда  возвращает HTTP ответ скодомсостояния, зависящего от  результата запроса.

Код ответаОписание
200 OKЗапрос был успешно обработан.
400 Bad RequestСинтаксическая ошибка
404 Not FoundЭлемент или страница не найдены

Формат возвращаемых данных

Возвращаемые данные могут быть  в формате  JSON, либо — XML.По умолчанию используется формат  JSON.Для задания формата, в котором будут возвращаться данные, используется заголовок запроса. Клиент отсылает заголовок Accept, в котором указывает желаемый формат ответа:

Accept: application/xml

или

Accept: application/json

Описание формата ответа отправляется в ответе в заголовке Content-Type.Возвращаемые  в ответе данные, представляют собой JSON строку (http://json.org/json-ru.html), которая в общем виде,  выглядет  следующим образом:

{
       "элемент_1":"значение_элемента_1",
       "элемент_2":"значение_элемента_2",
       "элемент_3":       {
               "свойство_1_элемента_3":"значение_свойства_1_элемента_3",
               "свойство_2_элемента_3":               [
                      "значение_1_свойства_2_элемента_3",
                      "значение_2_свойства_2_элемента_3"

         
      ]          
   },
      . . . .
}

Если в ходе выполнения запроса произошла ошибка — возвращается описание соответствующей ошибки, например:

{
      "errors":      [
              "      [
         _описание_ошибки_
      ]      "         
   ]
}

Работа с клиентами

Получение действующего токена клиента

МетодPOST
URLapi.lentainform.com/v1/auth/token

Передаваемые параметры:

ПараметрЗначение
emailАдрес электронной почты клиента, указанный при регистрации в системе lentainform
passwordПароль клиента, полученный при регистрации

Возвращаемый ответ:

{
    "token":"_текущий_токен_",
    "refreshToken":"_токен_для_обновления_"
    "idAuth":"_идентификатор_учетной_записи_клиента_"
}
_текущий_токен_

 используется для идентификации  клиента;

_токен_для_обновления_

— будет использован в последующих версиях для обновления просроченного текущего токена.

Работа с информерами

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

МетодGET
URLapi.lentainform.com/v1/publishers/{authId}/widgets

Передаваемые параметры (обязательные параметры выделены красным):

ПараметрЗначение
token_токен_клиента_
dateIntervalИнтервал, за который нужно получить статистику. Допустимые значения:
  • interval — при выборе ожидается передача еще параметров двух дат startDate/endDate в формате гггг-мм-дд
  • all — за все время
  • thisWeek — текущая неделя
  • lastWeek — прошлая неделя
  • thisMonth — текущий месяц
  • lastMonth — прошлый месяц
  • lastSeven — последние 7 дней
  • today — сегодня
  • yesterday — вчера
  • last30Days — последние 30 дней
siteIdЕсли указан — выводится статистика только по информерам, связанными с сайтом(ами). Может принимать несколько значений через запятую.
widgetIdID КИ. Если указан — выводится статистика только по указанному информеру(ам). Может принимать несколько значений через запятую.
timeZone
Смещение по времени отображаемой статистики в отношении указанной таймзоны. Список доступных таймзон здесь ( TZ )

Возвращаемый ответ:

{  
  "_dateInterval_":{  
     "_widgetId_":{  
        "impressions":"_показы_",
        "realImpressions":"_реальные показы_",
        "visibilityRate":"_% показов_",
        "clicks":"_клики_",
        "ctr":"_ctr_",
        "revenue":"_заработок_$_",
        "cpc":"_cpc_¢_",
        "cpm":"_cpm_$_"
     }
  }
}

Если информер работает только по обмену, то возвращаемый ответ будет следующий:

{  
  "_dateInterval_":{  
     "_widgetId_":{  
        "impressions":"_показы_",
        "realImpressions":"_реальные показы_",
        "visibilityRate":"_% показов_",
        "clicks":"_клики_",
        "ctr":"_ctr_"
     }
  }
}

Работа с cайтами

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

МетодGET
URLapi.lentainform.com/v1/publishers/{authId}/sites-stat

Работает только для обмена и внутреннего обмена.Передаваемые параметры (обязательные параметры выделены красным):

ПараметрЗначение
token_токен_клиента_
dateIntervalИнтервал, за который нужно получить статистику. Допустимые значения:
  • interval — при выборе ожидается передача еще параметров двух дат startDate/endDate в формате гггг-мм-дд
  • all — за все время
  • thisWeek — текущая неделя
  • lastWeek — прошлая неделя
  • thisMonth — текущий месяц
  • lastMonth — прошлый месяц
  • lastSeven — последние 7 дней
  • today — сегодня
  • yesterday — вчера
  • last30Days — последние 30 дней
siteIdЕсли указан — выводится статистика только по указанному сайту. Может принимать несколько значений через запятую.
timeZone Timeshift of statistics. Available list of timeZones here ( TZ )

Возвращаемый ответ:

{
   "_siteId_": {
       "_dateInterval_": {
           "toUsHits": _входящие_клики_,
           "fromUsHits": _исходящие_клики_,
           "exchangeRatio": "_коэффициент_обмена_"
       }
   }
}