API Bpium построено на идеологии REST, формат передачи данных — JSON.

Ресурсы

API состоит из ресурсов.

Информационная система (данные):

• ​отдел​

• ​каталог​

• ​запись​

• ​вид​

• ​файл​

Правовая политика:

• ​права​

Отчеты:

• ​дашборд​

• ​график​

Методы

Ресурсы имеют однотипные CRUD-методы: создания (Create), получения (Read), изменения (Update) и удаления (Delete). Большинство ресурсов имеют метод для получения коллекции объектов.

Для каждого метода используется свой HTTP-запрос:

• Получить ресурс — запрос GET

• Создать ресурс — запрос POST

• Изменить ресурс — запрос PATCH

• Удалить ресурс — запрос DELETE

• Получить коллекцию ресурсов — запрос GET

Формат

API Бипиума использует формат передачи данных JSON, кодировка utf-8.

HTTP-заголовок: content-type: application/json

Доступ к API

Относительный адрес API:

/api/v1/{ресурс}

Адрес API в облаке:

https://{вашдомен}.bpium.ru/api/v1/{ресурс}

Авторизация

Запросы к API проходят полноценную проверку прав доступа к данным. По этому все запросы должны быть выполнены от имени одного из сотрудников. Именно его права будут применены при исполнении запросов. Способы авторизации:

Базовая авторизация

Параметры передаются через HTTP-заголовок Authorization. Логин и пароль склеиваются через двоеточие и кодируются через функцию Base64. Пример:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Подробнее о стандарте: Basic authentication.

Некоторые веб-клиенты позволяют автоматически формировать заголовок базовой авторизации, если логин и пароль передан через URL (пример: https://login:pass@xxx.bpium.ru/...). Браузер Chrome, например, будет так делать, только если сервер пошлет специальный заголовок. Однако, сервер Bpium не отправляет такой заголовок, так как придерживается методологии REST.

Авторизация через POST

Авторизоваться в Bpium можно отправив POST-запрос на страницу авторизации:

https://{вашдомен}.bpium.ru/auth/login

Post-параметры: email и password.

В ответ на запрос сервер вернет сессионную cookie connect.sid, которая используется для последующей работы.

Авторизация через сессионную Cookie

Для использования установленной авторизации подписывайте запросы сессионной cookie connect.sid.

Часовой пояс

Сервер Bpium хранит даты в нулевом часовом поясе (UTC). Задача преобразования дат и времени в нужный часовой пояс лежит на стороне получателя (клиента). Однако, некоторые запросы требуют учета часового пояса клиента для выбора данных. Например, поиск по датам или построение графиков по датам.

Для этого инициатор API-запросов указывает часовой пояс через GET-параметр timezoneOffset. Значение параметра следует указывать в минутах. Например, для +3 часового пояса:

https://{вашдомен}.bpium.ru/api/v1/catalogs/5?timezoneOffset=180

Коды HTTP-ответов ошибок

• 400 — некорректный запрос (не верные параметры)

• 401 — ошибка авторизации

• 402 — необходима оплата лицензии

• 403 — доступ запрещён

• 404 — ресурс/объект не найден

• 405 — метод не разрешён

• 426 — необходима докупка лицензий

• 429 — превышено число допустимых запросов (лимит)

• 500 — неизвестная ошибка сервера

• 501 — метод не реализован

Лимиты

Бипиум лимитирует число запросов к API:

• 100 запросов за 30 секунд для одной учетной записи

• 1000 запросов за 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

Примеры использования

PHP

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

// домен и авторизация
$domen = 'ВАШДОМЕН.bpium.ru';
$user = 'abc@mail.ru';
$pass = 'mypass';
​
// номер каталога, в котором создать новую запись
$catalog_id = 13;
​
// массив значений полей новой записи
// ключи массива — идентификаторы полей
$values = array();
$values['2'] = ''; // строка для текстовых полей
$values['3'] = array('1'); // массив для полей типа категория, набор галочек, вопрос
$values['4'] = 17; // число для полей типа число, прогресс, звёзды
$values['5'] = date('Y-m-d') . "T" . date('H:i:s') . "+04:00"; // даты
​
// подготовка тела запроса
$data = array();
$data['values'] = $values;
$data_json = json_encode($data);
​
// запрос
$ch = curl_init("https://$domen/api/v1/catalogs/$catalog_id/records");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "$user:$pass");
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Content-Length: ' . strlen($data_json))
);
$result = curl_exec($ch);