API
Last updated
Last updated
API Bpium построено на идеологии , формат передачи данных — JSON.
API состоит из ресурсов.
Работа с пользовательскими и системными данными:
— список каталогов с описанием структуры полей
— список записей каталога с значением полей
— список записей, которые ссылаются на указанную запись
— список операций по изменению записи
— информация о файле в файловом хранилище
— список отделов (групп каталогов)
— список видов каталога с условиями фильтрации записей
Агрегация/сводные данные:
— разложение записей каталога по какому-либо полю с подсчетом сводных значений по другому полю
— подсчет сводного значения в каталоге по какому-либо полю
Отчеты:
— список экранов с графиками с описанием параметров графиков
— значения графика
Дополнительные поисковые выборки:
Правовая политика
Связанные с событиями и процессами:
Системные:
Компания (Company) — информация о текущей компании доступ
Компании (Companies) — список компаний, к которым пользователь имеет доступ
Лицензия (License) — информация о лицензии
Ресурсы имеют однотипные CRUD-методы: создания (Create), получения (Read), изменения (Update) и удаления (Delete). Ресурсы имеют только те методы, которые логически необходимы.
Получить коллекцию ресурсов — запрос GET
Получить ресурс — запрос GET
Создать ресурс — запрос POST
Изменить ресурс — запрос PATCH
Удалить ресурс — запрос DELETE
API Бипиума использует формат передачи данных JSON
, кодировка utf-8
.
HTTP-заголовок: content-type: application/json
Относительный адрес API:
Адрес API в облаке:
Запросы к API проходят полноценную проверку прав доступа к данным. По этому все запросы должны быть выполнены от имени одного из сотрудников. Именно его права будут применены при исполнении запросов. Способы авторизации:
Параметры передаются через HTTP-заголовок Authorization
. Логин и пароль склеиваются через двоеточие и кодируются через функцию Base64. Пример:
Некоторые веб-клиенты позволяют автоматически формировать заголовок базовой авторизации, если логин и пароль передан через URL (пример: https://login:pass@xxx.bpium.ru/...
). Браузер Chrome, например, будет так делать, только если сервер пошлет специальный заголовок. Однако, сервер Bpium не отправляет такой заголовок, так как придерживается методологии REST.
Авторизоваться в Bpium можно отправив POST-запрос на страницу авторизации:
Post-параметры: email
и password
.
Для использования установленной авторизации подписывайте запросы сессионной cookie sid
(или переменную с другим именем, которая задается в конфигурационном файле сервера). Для компаний в облаке bpium.ru сессионная cookie имеет название connect.sid
.
Формат передачи http-заголовка с сессионной cookie в hhtp-запросе к серверу:
Сервер Bpium хранит даты в нулевом часовом поясе (UTC). Задача преобразования дат и времени в нужный часовой пояс лежит на стороне получателя (клиента). Однако, некоторые запросы сервера требуют учета часового пояса клиента для выбора данных. Например, поиск записей по датам или построение графиков по датам. Если не передать часовой пояс клиента, то сервер найдет данные, которые не соответствуют ожиданиям клиента.
Для этого инициатор API-запросов указывает часовой пояс через GET-параметр timezoneOffset
. Значение параметра следует указывать в минутах. Например, для +3 часового пояса:
400 — некорректный запрос (не верные параметры, не прошла валидация)
401 — ошибка авторизации
402 — необходима оплата лицензии (не действует базовая лицензия)
403 — доступ запрещён по правам
404 — ресурс/объект не найден
405 — метод не разрешён для использования
426 — необходима докупка лицензий (доступ к модулям не входящим в лицензию)
429 — превышено число допустимых запросов (лимит частоты запросов)
500 — неизвестная ошибка сервера (не обработанное исключение в коде сервера)
501 — метод ресурса не существует или не реализован
Бипиум лимитирует число запросов к API. Параметры лимитирования запросов задаются в конфигурационном файле сервера, а так же могут быть изменены для каждой учетной записи (пользователя) индивидуально.
Для облака bpium.ru заданы следующие лимиты числа запросов:
100 запросов за 30 секунд для одной учетной записи
500 запросов за 30 секунд для одного IP-адреса
Если число запросов превышено, Бипиум вернет ошибку с HTTP-кодом 429 (Too Many Requests).
В коробочной версии Bpium Enterprise эти параметры задаются в конфигурационном файле:
LIMIT_USER_MAX_REQUESTS
(int) — максимальное число запросов от одного аккаунта за интервал. По умолчанию: 100
LIMIT_USER_REQUEST_DURATION
(int) — интервал оценки числа запросов от одного аккаунта. В миллисекундах. По умолчанию: 30000
LIMIT_IP_MAX_REQUESTS
(int) — максимальное число запросов с одного IP-адреса за интервал. По умолчанию: 1000
LIMIT_IP_REQUEST_DURATION
(int) — интервал оценки числа запросов с одного IP-адреса. В миллисекундах. По умолчанию: 30000
Для удобства работы с базовыми ресурсами и методами создана публичная библиотека:
Пример создания новой записи в каталоге:
— список записей, доступных для связывания в поле типа «связанный объект» (используется в выпадающем списке поля «связанный объект»)
— список сотрудников, доступных в системе (используется в выпадающем списке поля типа Сотрудник)
— список записей, которые можно выбрать как условие фильтра записей в поле типа «связанный объект»
— список записей всей системе с поиском по полю контакт
— список правил на доступ к объекту (отделу, каталогу, виду, записи)
Лайв-события (Changes) — запрос на вызов события «» для запуска сценария обработки значения полей, которые вводит сотрудник в анкете записи
— информация о текущем авторизованном пользователе
Подробнее о стандарте: .