Требования к адаптеру

Адаптер — компонент на стороне интегрируемой системы, который обеспечивает её взаимодействие с DataHUB. Ниже описан минимальный набор функций, которые должен реализовать любой адаптер.

Авторизация

Адаптер работает с Transport API исключительно по JWT-токенам.

Обязательные действия:

При запуске — получить пару Access + Refresh токенов через эндпоинт авторизации по логину и паролю.
При каждом запросе к Transport API — передавать Access-токен в заголовке Authorization: Bearer {accessToken}.
При получении 401 Unauthorized — обновить Access-токен через Refresh-токен и повторить запрос.
Если обновление Refresh-токена также вернуло 401 — прекратить обмен и потребовать повторной авторизации оператора.

Отправка сообщений

Адаптер должен уметь:

обнаруживать изменения объектов (через подписки на события, хуки, триггеры или иной механизм платформы);
сериализовать объект в тело сообщения (формат JSON);
оборачивать тело в транспортный конверт с обязательными полями (Id, Type, ClassId, Source, CreationTime, Body);
отправлять сообщение через Transport API;
буферизовать исходящие сообщения в локальной очереди — чтобы не потерять их при временной недоступности сервера.

Получение сообщений

Адаптер должен:

опрашивать сервер в цикле через Transport API (long-polling или short polling);
извлекать тело сообщения и идентификатор доставки из заголовка ответа;
в одной транзакции: положить сообщение в локальную очередь входящих и отправить подтверждение получения;
передавать сообщение в локальную очередь для последующей асинхронной обработки.

Локальные очереди

Адаптер хранит на своей стороне два буфера:

Очередь исходящих — сообщения, ожидающие отправки в DataHUB.
Очередь входящих — сообщения, принятые от DataHUB, ожидающие прикладной обработки.

Оба буфера независимы от доступности сервера DataHUB.

Идентификация объектов

При приёме входящего сообщения адаптер ищет соответствующий объект в локальной базе по массиву идентификаторов из разных систем. Алгоритм поиска описан в Идентификация объектов.

Идемпотентность входящих обработчиков

DataHUB гарантирует доставку at-least-once: одно и то же сообщение может быть доставлено более одного раза. Входящий обработчик обязан быть идемпотентным — повторная обработка одного сообщения не должна приводить к дублированию или искажению данных.

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

При ошибке обработчика:

сообщение остаётся в локальной очереди и повторяется через заданную задержку;
после исчерпания максимального числа попыток сообщение переводится в статус «Ошибка обработки» и требует ручного вмешательства.

Подробнее — в Обработка ошибок.