Data API

• Соглашения
• Пользователи API и аутентификация
• Добавить IP-адрес в список разрешенных
  • Доступ по ключу
  • Доступ по логину и паролю
• Отчет по запросам к API
• Базовый URL для доступа к API
• Версионность
• Лимиты и ограничения
  • Методы и их стоимость в баллах
  • Расширение лимитов
• Обработка ошибок
  • Параметры сообщения об ошибке
  • JSON структура ошибки
  • Группы кодов ошибок
    • Список ошибок общих для всех методов
    • Список ошибок для методов с глаголом get
    • Список ошибок общих для методов с глаголом delete
    • Список ошибок общих для методов с глаголом create и update, set, unset
  • Глаголы используемые в именовании методов
  • Критерии фильтрации
    • Возможные ошибки при фильтрации
    • Пример JSON структуры простого фильтра
    • Пример JSON структуры дерева фильтров с одним уровнем вложенности
    • Пример JSON структуры дерева фильтров с двойным уровнем вложенности
    • Пример JSON структуры дерева фильтров с тройным уровнем вложенности
    • Операторы фильтрации
  • Сортировка данных
    • Возможные ошибки при сортировки
  • Постраничный вывод
  • Мета-параметры
  • Представление возвращаемых данных
    • Отдельный список возвращаемых столбцов
    • Возможные ошибки в представлении возвращаемых данных
  • Общие поля для всех методов
  • Аутентификация

Соглашения

Приняты следующие соглашения при использовании Data API:

• Пустые поля всегда возвращаются в ответе со значением null. В случае массива возвращается пустой массив, в случае объекта возвращается пустой объект;
• Все поля связанные с датой и временем передаются в формате YYYY-MM-DD hh:mm:ss;
• Запросы к API выполняются всегда с помощью метода POST;
• Все параметры в запросах/ответах, а также в структурах данных в формате JSON и название методов именуются в стиле Snake Case - разделение слов через нижнее подчеркивание;
• Данные возвращаются только в JSON формате согласно спецификации RFC 7159. Заголовок Accept игнорируется;
• Кодировка данных UTF-8;
• Заголовок Content-Type должен быть "application/json; charset=UTF-8";
• Заголовок Content-Length должен содержать корректную длину сообщения, следуя спецификации HTTP/1.1

Добавить IP-адрес в список разрешенных

По умолчанию доступ к API запрещен всем, чтобы можно было делать запросы необходимо IP-адрес хоста с которого делается запрос добавить в белый список. Это можно сделать через личный кабинет "Администратор -> Аккаунт -> Правила и настройки безопасности" вкладка "API".

Если необходимо разрешить доступ всем IP-адресам, то нужно добавить в список разрешенных 0.0.0.0/0

Если запрос делается из под агента, то его IP адрес должен быть добавлен в белый список клиентского аккаунта

Пользователи API и аутентификация

К пользователям и ключам доступа применяются права доступа аналогичные правам доступа в личном кабинете

Доступ по ключу

Ключи генерируются на уровне пользователя в разделе личного кабинета "Аккаунт" → "Управление пользователями" Существует два типа ключей:

• Постоянный;
• Временный;

Постоянный ключ имеет неограниченное время действия. Временный ключ имеет конкретную дату окончания действия ключа.

Доступ по логину и паролю

Используется аутентификация с использованием сессий

Время жизни сессии 1 час.

Отчет по запросам к API

В личном кабинете "Отчеты"->"Служебные"->"Запросы к API" можно построить отчет по запросам к API

Базовый URL для доступа к API

Базовый URL для доступа к API соответствует следующему шаблону:

<protocol> :// <hostname> / <version>

• <protocol> - https;
• <hostname> - dataapi.comagic.ru, dataapi.uiscom.ru (в зависимости от проекта, где зарегистрирован портал);
• <version> - версия API (см. раздел Версионность)

Авторизационные данные портала uiscom не действительные для url https://dataapi.comagic.ru/ и наоборот

https://dataapi.comagic.ru/<version>

https://dataapi.uiscom.ru/<version>

Версионность

Текущая версия Data API 2.0

Data API поддерживает версионность. Версия указывается в базовом URL как vX.Y, где X - номер мажорной версии, Y - номер минорной версии

Если была выпущена новая версия, то старая считается устаревшей и соответственно при обращении к старой версии API в мета-параметрах (см. раздел Мета-параметры) будет возвращаться параметр "current_version_deprecated" со значением "true"

Максимальное количество поддерживаемых версий - 2 Период поддержки устаревшей версии 2 месяца

Лимиты и ограничения

Баллы списываются только за успешные запросы, т.е в отчете по запросам к API (см. раздел Отчет по запросам к API) он помечен как успешный.

Информация о лимитах возвращается во всех ответах в мета-парметрах (см. раздел Мета-параметры) кроме случаев когда лимиты не учитываются;

Лимиты построены по бальной системе, т.е каждый метод имеет свой вес. Вызов метода уменьшает доступные дневные/минутные баллы на размер веса вызываемого метода

Информация о лимитах в мета-параметрах:

Методы и их стоимость в баллах

Расширение лимитов

На странице "Аккаунт" -> "Тарифы и опции" в личном кабинете можно расширить лимиты.

Обработка ошибок

Параметры сообщения об ошибке

JSON структура ошибки

{
 "jsonrpc": "2.0",
 "id": null,
 "error": {
  "code": "number",
  "message": "string",
  "data": {
   "mnemonic": "string",
   "field": "string",
   "value": "string",
   "params": {
    "object": "string"
   },
   "extended_helper": "string",
   "metadata": {

   }
  }
 }
}

Группы кодов ошибок

Список ошибок общих для всех методов

Список ошибок для методов с глаголом get

Список ошибок общих для методов с глаголом delete

Список ошибок общих для методов с глаголом create и update, set, unset

Групповые операции

Функционал не поддерживается

Принцип именования методов

Имя JSON-RPC метода состоит из двух частей разделенных точкой: глагола и имени объекта.

Имя объекта выбирается как существительное во множественном числе, отражающее бизнес-сущность, например subscribers.

Имя метода должно начинаться с глагола, отражающего суть операции.

Глаголы используемые в именовании методов

Критерии фильтрации

Фильтрация данных применяется только к глаголу "get" (см. раздел "Глаголы используемые в именовании методов" с помощью необязательного примитива "filter", который является объектом и может содержать:

1. Простой фильтр;
2. Дерево фильтров которое содержит простые фильтры с условиями.

Простой фильтр - это объект, который содержит в себе обязательные примитивы:

• field - поле сущности к которой будет применяться фильтрация (список заранее определен для метода);
• operator - оператор фильтрации. Список всех операторов можно получить в разделе "Операторы фильтрации";
• value - значение для оператора фильтрации. Необязательное поле, если оно отсутствует, то считается пустота.

Дерево фильтров содержит специальный примитив "filters", который может содержать в себе как простые фильтры, так и дерево фильтров.

Возможные ошибки при фильтрации

Пример JSON структуры простого фильтра

Получаем список записей у которых поле "name" имеет имя "Bob"

{
 "jsonrpc":"2.0",
 "id":1,
 "method":"get.entity",
 "params":{
  "filter":{
   "field":"name",
   "operator":"=",
   "value":"Bob"
  }
 }
}

Пример JSON структуры дерева фильтров с одним уровнем вложенности

Получаем список записей у которых поле "name" имеет имя "Bob" и его возраст 25 лет

{
 "jsonrpc":"2.0",
 "id":1,
 "method":"get.entity",
 "params":{
  "filter":{
   "filters":[
    {
     "field":"name",
     "operator":"=",
     "value":"Bob"
    },
    {
     "field":"age",
     "operator":"=",
     "value":25
    }
   ],
   "condition":"and"
  }
 }
}

Пример JSON структуры дерева фильтров с двойным уровнем вложенности

Получаем список записей у которых поле "name" имеет имя "Bob" и его возраст 25 лет или список записей у которых поле "name" имеет имя "Dexter" и его возраст 2 года

{
 "jsonrpc":"2.0",
 "id":1,
 "method":"get.entity",
 "params":{
  "filter":{
   "filters":[
    {
     "filters":[
      {
       "field":"name",
       "operator":"=",
       "value":"Bob"
      },
      {
       "field":"age",
       "operator":"=",
       "value":25
      }
     ],
     "condition":"and"
    },
    {
     "filters":[
      {
       "field":"name",
       "operator":"=",
       "value":"Dexter"
      },
      {
       "field":"age",
       "operator":"=",
       "value":2
      }
     ],
     "condition":"and"
    }
   ],
   "condition":"or"
  }
 }
}

Пример JSON структуры дерева фильтров с тройным уровнем вложенности

Условие запроса ((addv_comp_id = 10 or addv_comp_id = 12) and (tag_id = 1 or tag_id = 5)) or visitor_id = 14 or (date_from = 2015-12-14 and date_till = 2015-12-16)

{
 "filter":{
  "filters":[
   {
    "filters":[
     {
      "filters":[
       {
        "field":"addv_comp_id",
        "operator":"=",
        "value":10
       },
       {
        "field":"addv_comp_id",
        "operator":"=",
        "value":12
       }
      ],
      "condition":"or"
     },
     {
      "filters":[
       {
        "field":"tag_id",
        "operator":"=",
        "value":1
       },
       {
        "field":"tag_id",
        "operator":"=",
        "value":5
       }
      ],
      "condition":"or"
     }
    ],
    "condition":"and"
   },
   {
    "field":"visitor_id",
    "value":14,
    "operator":"="
   },
   {
    "filters":[
     {
      "field":"date_from",
      "value":"2015-12-14 12:00:00",
      "operator":"="
     },
     {
      "field":"date_till",
      "value":"2015-12-16 15:00:00",
      "operator":"="
     }
    ],
    "condition":"and"
   }
  ],
  "condition":"or"
 }
}

Операторы фильтрации

Фильтрация null и not null будет =null, !=null

Сортировка данных

Сортировка данных применяется только к глаголу "get" (см. раздел "Глаголы используемые в именовании методов") с помощью массива объектов сортировки со следующими примитивами:

• field - поле по которому производится сортировка;
• order - направления сортировки. Возможные значения "asc"/"desc". "asc" - по возрастанию, "desc" - по убыванию. Параметр необязателен. Значение по умолчанию "asс".

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

Возможные ошибки при сортировки

JSON структура:

{
 "jsonrpc":"2.0",
 "id":"number",
 "method":"string",
 "params":{
  "sort":[
   {
    "field":"string",
    "order":"string"
   }
  ]
 }
}

Постраничный вывод

Постраничный вывод может быть применен к глаголу "get" (см. раздел "Глаголы используемые в именовании методов"). Для выполнения пагинации данных используются следующие параметры:

JSON структура:

{
 "jsonrpc":"2.0",
 "id":"number",
 "method":"string",
 "params":{
  "offset":"number",
  "limit":"number"
 }
}

Мета-параметры

Возвращаются при использовании глагола "get" (см. раздел "Глаголы используемые в именовании методов").

Присутствуют как в ошибочном, так и в успешном ответе

Параметр "api_version" возвращается только для версий которые deprecated.

JSON структура:

{
 "metadata":{
  "api_version":{
   "current_version_deprecated":"boolean",
   "current_version":"string",
   "latest_version":"string"
  },
  "limits":{
   "day_limit":"number",
   "day_remaining":"number",
   "day_reset":"number",
   "minute_limit":"number",
   "minute_remaining":"number",
   "minute_reset":"number"
  },
  "total_items":"number"
 }
}

Представление возвращаемых данных

Отдельный список возвращаемых столбцов

В глаголе получения данных "get" (см. раздел "Глаголы используемые в именовании методов") может быть указан специальный необязательный примитив "fields" с типом массив, который может содержать список полей которые необходимо показать в выводе. Если примитив "fields" не используется, то в выводе показываются все поля по умолчанию для вызываемого метода.

Список полей индивидуален для каждого метода.

JSON структура:

{
 "jsonrpc":"2.0",
 "id":"number",
 "method":"string",
 "params":{
  "fields":[
   "string"
  ]
 }
}

Возможные ошибки в представлении возвращаемых данных

Общие поля для всех методов

Аутентификация

Список доступных методов