REST API

Материал из Wiki
Версия от 15:41, 25 ноября 2019; Admin (обсуждение | вклад)
(разн.) ← Предыдущая | Текущая версия (разн.) | Следующая → (разн.)
Перейти к: навигация, поиск

REST API v1.0

Access-токен для OAuth2

Для аутентификации и авторизации в API используется протокол OAuth2 по схеме Client Credentials Grant.

Эта схема протокола OAuth2 позволяет пользователю взаимодействовать с API напрямую. Для пользователя создаётся клиент с параметрами client_id и client_secret, пользуясь которыми он сам получает access-токен для аутентификации в API.

clinetId и clientSecret вы можете получить оставив нам заявку.

При grant_type=client_credentials метод создаёт новый access-токен по паре client_id, client_secret, получаемой при регистрации OAuth-клиента.

Это реализация схемы Client Credentials Grant протокола OAuth2.

Запрос 

POST /token HTTP/2
Host: https://api.hybrid.ru
Content-Type: application/x-www-form-urlencoded
  1. grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}
  2. grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}&advertiserId={advertiserId} - сгенерировать токен от имени агенства для рекламного аккаунта.

При grant_type=refresh_token метод создаёт новый access-токен взамен старого, который идентифицируется переданным параметром refresh_token.

В случае, если вызов осуществляется от агентского аккаунта вы можете сгенерировать токен для своего рекламодлателя передав дополнительный параметр в теле запроса (2).

Пример ответа 

HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
{
  "access_token": "{access_token}",
  "token_type": "bearer",
  "scope": "{scope}",
  "expires_in": "86400",
  "refresh_token": "{refresh_token}"
}

Истечение срока действия access-токена

Каждый полученный access-токен является действительным в течение суток. На это указывает свойство expires_in в ответе на запрос access-токена. Там же указывается refresh_token — специальный токен для получения нового access-токена. За это отвечает схема Refreshing an Access Token в протоколе OAuth2.

Запрос 

POST /token HTTP/2
Host: https://api.hybrid.ru
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}

Пример ответа 

HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
 
{
  "access_token": "{new_access_token}",
  "token_type": "bearer",
  "expires_in": "86400",
  "refresh_token": "{refresh_token}"
}

Получение списков рекламодателей для аккаунта агентства

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

Запрос 

GET /v2.0/agency/ HTTP/2
Host: https://api.hybrid.ru
Authorization: Bearer {access_token}

В ответ вы получите массив объектов c полями:

  1. id - идентификатор рекламодателя
  2. name - название рекламодателя

Пример ответа: 

HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
[
  {
    "Id": "53df8633af55cd57805746f5",
    "Name": "Advertiser 1"
  },
  {
    "Id": "54f74d70870a8e44a023ghj5",
    "Name": "Advertiser 2"
  },
  {
    "Id": "5593b2ab9341f9b09819dq45",
    "Name": "Advertiser 3"
  }
]

После получения списка рекламодателей вы можете запросить токен для отдельного рекламодателя (1) и осуществлять с его помощью все вызовы к api.

Получение рекламных кампаний

GET /v2.0/advertiser/{advertiserId} HTTP/2
Host: https://api.hybrid.ru
Authorization: Bearer {access_token}
  1. advertiserId - идентификатор рекламодателя

Пример ответа 

HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
[
  {
    "Id": "53df8633af55cd57805746f5",
    "Name": "Campaign 1"
  },
  {
    "Id": "54f74d70870a8e44a023ghj5",
    "Name": "Campaign 2"
  },
  {
    "Id": "5593b2ab9341f9b09819dq45",
    "Name": "Campaign 3"
  }
]

Получение баннеров по указанной рекламной кампании

Запрос 

GET /v2.0/campaign/{campaignId}  HTTP/2
Host: https://api.hybrid.ru
Authorization: Bearer {access_token}

где campaign_id - идентификатор рекламной кампании.

Пример ответа 

HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
 
[
    {
        "Id": "58c1598f7bc72f277c4744ec",
        "Name": "Banner 1"
    },
    {
        "Id": "58c1598f7bc72f277c474408",
        "Name": "Banner 2"
    },
    {
        "Id": "58c1598f7bc72f277c474424",
        "Name": "Banner 3"
    },
    {
        "Id": "58c1598f7bc72f277c474440",
        "Name": "Banner 4"
    }
]

Получение статистики рекламного агентства

Запрос 

GET v2.0/agency/{split}?from={from}&to={to}&page={page}&limit={limit}
HTTP/2
Host: https://api.hybrid.ru
Authorization: Bearer {access_token}
Параметры
  • split - срез статистики
    • os - операционные системы
    • device - устройства
    • ssp
    • month - месяцы
    • day - дни
    • hour - часы
    • country - страны
    • region - регионы
    • advertiser - рекламодатели
    • campaign - кампании
    • banner - баннеры
    • bannersize - размеры баннеров
    • utm - utm метки
  • from - нижний порог даты статистики (обязательный параметр)
  • to - верхний порог даты статистики (обязательный параметр)
  • page - номер страницы начиная с 0 (по умолчанию 0)
  • limit - количество строк на странице (по умолчанию 100)

Дату необходимо передавать в формате ISO-8601.

Пример ответа 

HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
 
{
    "Statisitic": [
        {
            "Device": "Unknown",
            "ClickCount": 527,
            "ImpressionCount": 5909,
            "Reach": 3758,
            "Frequence": 1.5723789249600852,
            "Install": 0,
            "PostClickConversionsCount": 0,
            "PostViewConversionsCount": 0,
            "Cost": 65.9121155297415
        },
        {
            "Device": "Desktop",
            "ClickCount": 1951,
            "ImpressionCount": 855180,
            "Reach": 592994,
            "Frequence": 1.4421393808369056,
            "Install": 0,
            "PostClickConversionsCount": 5,
            "PostViewConversionsCount": 104,
            "Cost": 12821.089281889
        },
        {
            "Device": "Mobile",
            "ClickCount": 834,
            "ImpressionCount": 411352,
            "Reach": 316451,
            "Frequence": 1.2998916103914981,
            "Install": 0,
            "PostClickConversionsCount": 40,
            "PostViewConversionsCount": 8,
            "Cost": 5062.60356450518
        },
        {
            "Device": "Tablet",
            "ClickCount": 211,
            "ImpressionCount": 119425,
            "Reach": 81358,
            "Frequence": 1.4678949826691905,
            "Install": 0,
            "PostClickConversionsCount": 20,
            "PostViewConversionsCount": 8,
            "Cost": 1342.02392719788
        }
    ],
    "Total": {
        "ClickCount": 3523,
        "ImpressionCount": 1391866,
        "Reach": 992371,
        "Frequence": 1.4025661773671339,
        "Install": 0,
        "PostClickConversionsCount": 65,
        "PostViewConversionsCount": 120,
        "Cost": 19291.6288891218
    }
}

Получение статистики рекламодателя

Запрос 

GET v2.0/advertiser/{split}?from={from}&to={to}&page={page}&limit={limit}&id={id}
HTTP/2
Host: https://api.hybrid.ru
Authorization: Bearer {access_token}
Параметры
  • split - срез статистики
    • os - операционные системы
    • device - устройства
    • ssp
    • month - месяцы
    • day - дни
    • hour - часы
    • country - страны
    • region - регионы
    • campaign - кампании
    • banner - баннеры
    • bannersize - размеры баннеров
    • utm - utm метки
  • from - нижний порог даты статистики (обязательный параметр)
  • to - верхний порог даты статистики (обязательный параметр)
  • page - номер страницы начиная с 0 (по умолчанию 0)
  • limit - количество строк на странице (по умолчанию 100)
  • id - идентификатор рекламодателя

Дату необходимо передавать в формате ISO-8601.

Пример ответа 

HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
 
{
    "Statisitic": [
        {
            "Os": "Unknown",
            "ClickCount": 57,
            "ImpressionCount": 1,
            "Reach": 1,
            "Frequence": 1,
            "Install": 0,
            "PostClickConversionsCount": 0,
            "PostViewConversionsCount": 0,
            "Cost": 0
        },
        {
            "Os": "Android",
            "ClickCount": 11,
            "ImpressionCount": 1712,
            "Reach": 1052,
            "Frequence": 1.6273764258555132,
            "Install": 0,
            "PostClickConversionsCount": 0,
            "PostViewConversionsCount": 0,
            "Cost": 75.1080443749507
        },
        {
            "Os": "Ios",
            "ClickCount": 0,
            "ImpressionCount": 524,
            "Reach": 281,
            "Frequence": 1.8647686832740213,
            "Install": 0,
            "PostClickConversionsCount": 0,
            "PostViewConversionsCount": 0,
            "Cost": 13.273988726932
        },
        {
            "Os": "Linux",
            "ClickCount": 0,
            "ImpressionCount": 21,
            "Reach": 19,
            "Frequence": 1.105263157894737,
            "Install": 0,
            "PostClickConversionsCount": 0,
            "PostViewConversionsCount": 0,
            "Cost": 0.257097037557959
        },
        {
            "Os": "Windows",
            "ClickCount": 7,
            "ImpressionCount": 5711,
            "Reach": 4129,
            "Frequence": 1.383143618309518,
            "Install": 0,
            "PostClickConversionsCount": 0,
            "PostViewConversionsCount": 0,
            "Cost": 42.4643435702017
        }
    ],
    "Total": {
        "ClickCount": 75,
        "ImpressionCount": 7969,
        "Reach": 5482,
        "Frequence": 1.4536665450565487,
        "Install": 0,
        "PostClickConversionsCount": 0,
        "PostViewConversionsCount": 0,
        "Cost": 131.103473709642
    }
}

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

Запрос 

GET v2.0/campaign/{split}?from={from}&to={to}&page={page}&limit={limit}&id={id}
HTTP/2
Host: https://api.hybrid.ru
Authorization: Bearer {access_token}
Параметры
  • split - срез статистики
    • os - операционные системы
    • device - устройства
    • ssp
    • month - месяцы
    • day - дни
    • hour - часы
    • country - страны
    • region - регионы
    • banner - баннеры
    • bannersize - размеры баннеров
    • utm - utm метки
  • from - нижний порог даты статистики (обязательный параметр)
  • to - верхний порог даты статистики (обязательный параметр)
  • page - номер страницы начиная с 0 (по умолчанию 0)
  • limit - количество строк на странице (по умолчанию 100)
  • id - идентификатор кампании

Дату необходимо передавать в формате ISO-8601.

Пример ответа 

HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
 
{
    "Statisitic": [
        {
            "Banner": "58b54fce7bc72f21ac0f6125",
            "ClickCount": 57,
            "ImpressionCount": 500,
            "Reach": 410,
            "Frequence": 0,
            "Install": 0,
            "PostClickConversionsCount": 0,
            "PostViewConversionsCount": 0,
            "Cost": 0
        },
        {
            "Banner": "52b54fce7bc72f21ac0f6335",
            "ClickCount": 60,
            "ImpressionCount": 500,
            "Reach": 410,
            "Frequence": 0,
            "Install": 0,
            "PostClickConversionsCount": 0,
            "PostViewConversionsCount": 0,
            "Cost": 0
        }
    ],
    "Total": {
        "ClickCount": 117,
        "ImpressionCount": 1000,
        "Reach": 820,
        "Frequence": 0,
        "Install": 0,
        "PostClickConversionsCount": 0,
        "PostViewConversionsCount": 0,
        "Cost": 0
    }
}

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

Запрос 

GET v2.0/banner/{split}?from={from}&to={to}&page={page}&limit={limit}&id={id}
HTTP/2
Host: https://api.hybrid.ru
Authorization: Bearer {access_token}
Параметры
  • split - срез статистики
    • os - операционные системы
    • device - устройства
    • ssp
    • month - месяцы
    • day - дни
    • hour - часы
    • country - страны
    • region - регионы
    • bannersize - размеры баннера
    • utm - utm метки
  • from - нижний порог даты статистики (обязательный параметр)
  • to - верхний порог даты статистики (обязательный параметр)
  • page - номер страницы начиная с 0 (по умолчанию 0)
  • limit - количество строк на странице (по умолчанию 100)
  • id - идентификатор баннера

Дату необходимо передавать в формате ISO-8601.

Пример ответа 

HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
 
{
    "Statisitic": [
        {
            "Date": "2017-03-01T00:00:00",
            "ClickCount": 28,
            "ImpressionCount": 90,
            "Reach": 80,
            "Frequence": 0,
            "Install": 0,
            "PostClickConversionsCount": 0,
            "PostViewConversionsCount": 0,
            "Cost": 0
        },
        {
            "Date": "2017-03-02T00:00:00",
            "ClickCount": 29,
            "ImpressionCount": 100,
            "Reach": 82,
            "Frequence": 0,
            "Install": 0,
            "PostClickConversionsCount": 0,
            "PostViewConversionsCount": 0,
            "Cost": 0
        }
    ],
    "Total": {
        "ClickCount": 57,
        "ImpressionCount": 190,
        "Reach": 160,
        "Frequence": 0,
        "Install": 0,
        "PostClickConversionsCount": 0,
        "PostViewConversionsCount": 0,
        "Cost": 0
    }
}

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

Запрос 

GET v2.0/ssp?from={from}&to={to}
HTTP/2
Host: https://api.hybrid.ru
Authorization: Bearer {access_token}
Параметры
  • from - нижний порог даты статистики (обязательный параметр)
  • to - верхний порог даты статистики (обязательный параметр)

Дату необходимо передавать в формате ISO-8601.

Пример ответа 

HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
 
{
    "Statisitic": [
        {
            "Day": "2017-03-01T00:00:00",
            "WinCount": 0,
            "ClickCount": 147,
            "ImpressionCount": 152082,
            "StartEventsCount": 0,
            "SkipEventCount": 0,
            "UnmuteEventCount": 0,
            "MuteEvenCount": 0,
            "PauseEventCount": 0,
            "RewindEventCount": 0,
            "FullscreenEventCount": 0,
            "CollapseEventCount": 0,
            "FirstQuartileEventCount": 0,
            "MidpointEventCount": 0,
            "ThirdQuartileEventCount": 0,
            "CompleteEventCount": 0,
            "ResumeEventCount": 0,
            "ExpandEventCount": 0,
            "AcceptInvitationEventCount": 0,
            "CloseEventCount": 0,
            "Cost": 1154.38055297814
        },
        {
            "Day": "2017-03-02T00:00:00",
            "WinCount": 0,
            "ClickCount": 159,
            "ImpressionCount": 207508,
            "StartEventsCount": 0,
            "SkipEventCount": 0,
            "UnmuteEventCount": 0,
            "MuteEvenCount": 0,
            "PauseEventCount": 0,
            "RewindEventCount": 0,
            "FullscreenEventCount": 0,
            "CollapseEventCount": 0,
            "FirstQuartileEventCount": 0,
            "MidpointEventCount": 0,
            "ThirdQuartileEventCount": 0,
            "CompleteEventCount": 0,
            "ResumeEventCount": 0,
            "ExpandEventCount": 0,
            "AcceptInvitationEventCount": 0,
            "CloseEventCount": 0,
            "Cost": 1725.49061265143
        }
    ],
    "Total": {
        "Day": "0001-01-01T00:00:00",
        "WinCount": 0,
        "ClickCount": 306,
        "ImpressionCount": 359590,
        "StartEventsCount": 0,
        "SkipEventCount": 0,
        "UnmuteEventCount": 0,
        "MuteEvenCount": 0,
        "PauseEventCount": 0,
        "RewindEventCount": 0,
        "FullscreenEventCount": 0,
        "CollapseEventCount": 0,
        "FirstQuartileEventCount": 0,
        "MidpointEventCount": 0,
        "ThirdQuartileEventCount": 0,
        "CompleteEventCount": 0,
        "ResumeEventCount": 0,
        "ExpandEventCount": 0,
        "AcceptInvitationEventCount": 0,
        "CloseEventCount": 0,
        "Cost": 2879.87116562957
    }
}
Источник — «http://wiki.hybrid.ru/index.php?title=REST_API&oldid=198»