Skip to content

Особенности работы API

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

В качестве транспортного протокола используется HTTP 1.1.

Для обеспечения безопасности при передаче данных используется TLS-шифрование.

Поддерживаются следующие форматы возвращаемых данных:

  • JSON

Для задания формата ответа необходимо использовать http-заголовок “Accept”.

Для получения ответа в формате json: Accept: application/json

По умолчанию ответ возвращается в json формате.

Поддержка сессий

API не поддерживает серверные сессии, т.е. является stateless. Аутентификация запросов производится при обработке каждого запроса.

Асинхронный режим выполнения запросов

Некоторые функции API поддерживают асинхронный режим выполнения. Режим выполнения определяется при вызове параметром async. Если параметр async = true, то функция выполняется асинхронно. По умолчанию все функции API выполняются синхронно.

Асинхронный режим предполагает следующий алгоритм выполнения:

  1. При вызове функции на сервере происходит регистрация задачи и в ответе возвращается идентификатор задачи (атрибут operationToken).

  2. Далее задача выполняется на сервере.

  3. Для получения результата клиент вызывает функцию getAsyncResult, передавая в качестве параметра полученный на первом шаге operationToken:

Если задача выполнена, то будет возвращен результат выполнения.

Если задача находится в процессе выполнения, то будет возвращен resultCode= -29, «Задача выполняется».

Если задача не была выполнена в течение заданного(согласованного) таймаута, то возвращается resultCode= -40, «Таймаут выполнения запроса».

Если истек срок хранения результата на сервере, то возвращается resultCode= -30, «Срок результата истек».

Дополнительно, после завершения выполнения задачи может происходить вызов callback функции на стороне клиента с передачей результатов выполнения (при условии включения соответствующей настройки, согласовывается при подключении к API).

Особенности выполнения callback-вызова

Обратные вызовы (callbacks) - это специализированный набор функций API, с помощью которого вы можете можете получать результат асинхронного запроса сразу после его завершения. Простыми словами, вместо того чтобы посылать запросы на наш сервер, как бы вы это делали в случае с обычным асинхронным запросом, вы наоборот будете принимать запросы от нас и обрабатывать их на своей стороне.

  • Адрес callback вызова может передаваться с каждым запросом (параметр asyncCallback), либо настраиваться в системе для всех запросов.

  • Тип callback вызова – HTTP POST.

  • Формат ответа – application/json.

  • При вызове callback для авторизации запросов на стороне клиента могут использоваться следующие схемы:

NONE – без авторизации, может использоваться только на этапе тестирования

BASIC – HTTP BASIC AUTH, авторизационная информация передается в заголовке Authorization: Basic «base64 encoded user+pass»

TOKEN – авторизация по токену, токен передается в заголовке Authorization: Token «token»

BEARER – авторизация по токену , токен передается в заголовке Authorization: Bearer «token»