selena-online RESTful API

Документация описывает API, с помощью которого приложения могут взаимодействовать с базами данных пользователей системы online-бронирования Селена (https://selena-crm.ru). Взаимодействие подразумевает получение информации о наличии мест на туристических объектах (круизах, в санаториях, базах отдыха и т.д.), обмен информацией с бухгалтерскими системами учёта, а также бронирование мест.

Архитектура

API реализован в архитектуре REST. REST является архитектурным стилем, и в настоящий момент нет единого стандарта для разработки RESTful-приложений. Из этого следует, что мы не даём гарантии, что API будет полностью соответствовать общепринятым мнениям о том, как нужно проектировать REST-приложения, а также предпочтениям разработчика. Однако разработчик может расчитывать на то, что API в целом соответствует концепции REST.

Доступ к данным

В соответствии с архитектурой RESTful-приложений доступ к данным осуществляется с помощью HTTP-запросов с использованием методов GET, POST и т.д. Авторизация выполняется при помощи Base HTTP Authentication.

В общем случае не подразумевается обращение к функциям сервиса при помощи браузера. Однако в целях первичного ознакомления либо отладки собственного приложения разработчик может использовать плагины к браузеру, позволяющие отправлять специальные заголовки в HTTP-запросе. В качестве примера можно привести плагин Advanced Rest Client для Google Chrome.

Ещё один "визуальный" способ - утилита curl. Пример использования в Linux:

curl -H "Accept: application/xml" -u username:password -i https://selena-online.ru/rest/v1/roomlist?apartmentid=24

Формат данных

Поддерживаемые MIME-типы: application/json и application/xml. Если запрос предусматривает передачу входных данных в xml или json, то тип данных нужно указать в http-заголовке Content-Type. Тип возвращаемых данных указывается в заголовке Accept (по умолчанию). Для того, чтобы обеспечить разработчику возможность валидации XML, все возвращаемые данные содержат ссылки на XSD-схемы с подробными комментариями.

Кодировка входных и выходных данных - utf-8.

Функциональность

Функционал сервиса разделён на разделы, каждый из которых выполняет определённые задачи:

FrontAPI - справочники, наличие мест.
DocAPI - заказы и платежи.
BookingAPI - бронирование.
ProfileAPI - профиль покупателя, Личный кабинет.
SyncAPI - синхронизация данных.
HookAPI - система вэб-хуков.

Ограничения

Количество запросов с одного IP регулируется внутренней политикой сервиса. Политика может изменяться в зависимости от текущей нагрузки на сервис, а также при возникновении стрессовых ситуаций. При превышении количества запросов возвращается http 429. На все запросы, включая избыточные, возвращается заголовок X-API-Request-Limit, в котором указано действующее ограничение в формате n/t, где:

n - максимальное количество запросов
t - интервал времени: m - минута, s - секунда

Например, X-API-Request-Limit: 2/s - 2 запроса в секунду. Разработчик может использовать этот заголовок для автоматической настройки тайминга в своём коде.

Рекомендация, которая позволит нам в стрессовой ситуации решать проблему, не роняя ваши запросы: реализуйте в своём коде простую функцию-диспетчер, через которую отправляйте все запросы к API. В функции при получении ошибки 5хх делайте паузу в несколько секунд и повторяйте запрос. Хорошим решением будет установка лимита попыток, и при превышении отправка предупреждения. Анализируйте X-API-Request-Limit и устанавливайте скорость запросов автоматически. При получении 429 (превышение лимита) уменьшите скорость: возможно, вы просто попадаете в граничное состояние.

Одновременные запросы (многопоточность) с одного API-аккаунта: запрещены. Запросы подаются последовательно, один за другим.