Citeck WebAPI
Citeck WebAPI — основной низкоуровневый способ общения микросервисов между собой в пределах Citeck. Общение происходит по схеме Запрос → Ответ. Клиентский API предоставляет асинхронные методы с Promise и синхронные методы, ожидающие результат.
API для работы с WebAPI описано в ecos-webapp-api (репозиторий ecos-webapp-api).
Реализация API находится в ecos-webapp-lib (репозиторий ecos-webapp-commons).
Что обеспечивает Citeck WebAPI
№ |
Возможность |
|---|---|
1 |
Единообразная обработка ошибок executor’а до начала записи ответа: WebAPI формирует ответ со статусом |
2 |
Потоковый доступ к телу запроса и ответа позволяет обрабатывать большие объёмы данных без загрузки всего тела в память. Для этого доступны |
3 |
WebAPI позволяет не ломать голову над отправкой структурированных данных вместе с бинарными — в одном запросе предусмотрены обе части. |
4 |
WebAPI абстрагирует отправителя и получателя от способа доставки сообщений. Это позволяет независимо дорабатывать возможности транспорта, не изменяя прикладной код. К вопросам транспорта относятся, например, следующие аспекты системы:
|
5 |
WebAPI позволяет независимо настраивать сжатие всего сообщения, метаданных и тела. Сжатие может уменьшить объём передаваемых данных; выигрыш во времени зависит от данных, канала связи и затрат на сжатие. По умолчанию сжатие отключено. |
6 |
WebAPI позволяет в библиотеках реализовывать клиент-серверное общение между приложениями без добавления тяжёлых зависимостей вроде Spring MVC или различных HTTP-клиентов. |
7 |
Версионирование API позволяет ещё до выполнения запроса узнать, поддерживается ли он на принимающей стороне, включая диапазон поддерживаемых версий. Например, если клиент умеет общаться с эндпоинтом |
8 |
Асинхронность на уровне API. Методы |
Пример использования со стороны клиента:
Java:
EcosWebClientApi webClient;
int apiVersion = webClient.getApiVersion("emodel", "/custom/request", 2); // 2 — максимальная версия, поддерживаемая клиентом
if (apiVersion < 0) {
throw new IllegalStateException("WebAPI endpoint is unavailable or incompatible: " + apiVersion);
}
// Здесь должен быть код, который в зависимости от apiVersion подготовит тело запроса
String result = webClient.newRequest()
.targetApp("emodel") // целевое приложение
.path("/custom/request") // целевой путь (эндпоинт) запроса
.version(apiVersion) // если предполагается поддержка только нулевой версии, то эту строчку можно опустить
.header("custom-1", "value-1") // произвольные структурированные данные, которые можно
.header("custom-2", "value-2") // прочитать на принимающей стороне
.bodyJ((writer) -> { writer.writeText("request-text"); })
.executeJ((resp) -> { return resp.getBodyReader().readAsText(); })
.get();
Этот пример синхронно ожидает результат в get() и читает тело ответа целиком. В текущей реализации writeText() автоматически выбирает формат TEXT_UTF8, если запись тела ещё не началась. При использовании writeStream() закрывать переданный входной поток должен вызывающий код.
Пример использования со стороны сервера:
Java:
import kotlin.Pair;
class CustomExecutor implements EcosWebExecutor {
@Override
public void execute(@NotNull EcosWebExecutorReq req, @NotNull EcosWebExecutorResp resp) {
int apiVer = req.getApiVersion();
// тут может быть логика для обработки разных версий API
String requestText = req.getBodyReader().readAsText();
resp.setHeader("custom-header", "custom-value"); // хидеры можно использовать для любых данных
resp.getBodyWriter().writeText(requestText + "-response");
}
@NotNull
@Override
public Pair<Integer, Integer> getApiVersion() {
return new Pair<>(0, 2); // поддерживаются версии от 0 до 2
}
@NotNull
@Override
public String getPath() {
return "/custom/request";
}
@Override
public boolean isReadOnly() {
return false;
}
}
...
EcosWebExecutorsApi executorsApi;
executorsApi.register(new CustomExecutor());
Версионирование API
Микросервис публикует сведения о зарегистрированных executor’ах и диапазонах их версий через discovery-сервис. В текущей реализации сведения хранятся в ZooKeeper и доступны через кеш discovery-сервиса.
Метод getApiVersion(targetApp, path, maxVersion) использует эти сведения и возвращает максимальную совместимую версию executor’а, не превышающую maxVersion. Перед отправкой запроса необходимо обработать отрицательные результаты:
Значение |
Константа |
Описание |
|---|---|---|
|
|
Приложение недоступно. |
|
|
Путь не поддерживается приложением. |
|
|
Минимальная версия executor’а выше максимальной версии клиента. |
Версия запроса в клиентском builder’е по умолчанию равна 0; диапазон executor’а по умолчанию — от 0 до 0. Метод version() можно опустить, если используется нулевая версия.
Версия executor’а и версия транспортного протокола Citeck WebAPI — разные значения. Транспорт поддерживает версии 0 и 1; клиент выбирает меньшую из текущей версии протокола (1) и версии, опубликованной целевым приложением.
Описание запроса и ответа
Запрос формируется по следующему паттерну:
Версия транспортного протокола Citeck WebAPI (целое число);
Тип сжатия всего последующего содержимого (целое число);
Размер сжатых метаданных в байтах включая тип метаданных и тип сжатия (целое число);
Тип метаданных (целое число);
Тип сжатия метаданных (целое число);
Метаданные (зависит от типа метаданных (4))
Тип тела запроса (целое число)
Тип сжатия тела запроса (целое число; отсутствует, если тип тела —
NONE)Тело запроса (зависит от типа тела запроса (7); отсутствует при
NONE)
Ответ формируется по тем же принципам, что и запрос, но без указания версии транспортного протокола (1).
Структура метаданных запроса:
Примечание
В формате CBOR-массива поля определяются по позиции. Порядок строк таблицы ниже соответствует порядку элементов массива. Типы в таблице — типы Kotlin; особенности представления в потоке указаны в описаниях.
Поле |
Тип |
Описание |
|---|---|---|
|
|
JWT-токен с информацией о текущей аутентификации. |
|
|
Путь для обращения к нужному executor’у. |
|
|
Версия запроса для executor’а. |
|
|
Заголовки запроса (произвольные структурированные данные). |
|
|
Роуты, которые следует использовать для внешних запросов. Ключ — имя приложения, значение — идентификатор инстанса приложения. |
|
|
Поле тенанта. В текущей реализации клиент передаёт пустую строку; перенос тенанта из контекста не реализован. |
|
|
Часовое смещение относительно UTC. В потоке передаётся целым числом минут. |
|
|
Информация о клиенте (IP-адрес). |
|
|
Идентификатор транзакции. В потоке передаётся строкой. |
|
|
Список локалей. В потоке передаётся массивом языковых тегов. |
|
|
Данные контекста наблюдаемости Micrometer. |
|
|
Источник запроса в формате |
|
|
Данные вложенности транзакции: массив |
Массив содержит 12 элементов без txnNesting или 13 элементов при его наличии.
Структура метаданных ответа:
Примечание
Имена полей не играют роли, если тип метаданных — массив.
Поле |
Тип |
Описание |
|---|---|---|
|
|
Заголовки ответа (произвольные структурированные данные). |
|
|
Статус выполнения запроса. Поддерживается |
|
|
Роуты, которые следует использовать для внешних запросов. Ключ — имя приложения, значение — идентификатор инстанса приложения. |
|
|
Транзакционные данные (структура — ниже). |
Структура TxnRespData:
Поле |
Тип |
Описание |
|---|---|---|
|
|
Транзакционные действия, сгруппированные по типу. Клиент добавляет их в текущую транзакцию; порядок исполнения определяется механизмом транзакций. |
|
|
Устаревшее поле для совместимости: список приложений — участников транзакции. Сервер продолжает заполнять его вместе с |
|
|
Соответствие приложений наборам идентификаторов транзакционных ветвей (XID). Клиент регистрирует их в текущей транзакции. |
Поддерживаемые типы сжатия:
ID типа сжатия |
Тип сжатия |
|---|---|
0 |
Без сжатия |
1 |
ZSTD (Zstandard) |
2 |
LZ4 |
LZ4 используется начиная с версии 1 транспортного протокола. Если в настройках выбран LZ4, а используется протокол версии 0, применяется режим без сжатия. Это ограничение относится к версии протокола, а не к версии executor’а.
Поддерживаемые типы метаданных:
ID типа метаданных |
Тип метаданных |
|---|---|
0 |
CBOR массив с данными, где имя поля определяется по порядковому индексу. |
Поддерживаемые типы тела:
ID типа тела |
Тип тела |
|---|---|
0 |
NONE — тело отсутствует |
1 |
BINARY - бинарные данные |
2 |
CBOR - структурированные данные в формате CBOR |
3 |
JSON - структурированные данные в формате JSON |
4 |
TEXT_UTF8 - текстовые данные |
Бинарное представление целого числа в Citeck WebAPI:
Если число в диапазоне от 0 до 127 включительно, то мы его записываем как есть в виде одного байта.
Если число не в диапазоне от 0 до 127, то мы первый байт формируем следующим образом (по битам):
Биты |
Значение |
|---|---|
0–2 |
Кодируют количество байт, в которых закодировано число. Для кодирования берётся количество байт (например, 2) и вычитается единица (получаем 1). Таким образом, |
3–5 |
Не используются. |
6 |
Определяет знак «минус». Если равен 1, число отрицательное. Особый случай |
7 |
Определяет, что число не входит в диапазон от 0 до 127. |
Далее на основе битов 0–2 определяется количество байт полезной части. Байты записываются от старшего к младшему (big-endian); реализация для Int допускает от 1 до 4 байт. Если бит 6 выставлен в 1, результат умножается на -1.
Особый случай — Int.MIN_VALUE (-2147483648): бит знака в заголовке не устанавливается, а полезная часть содержит четыре байта 80 00 00 00. При чтении в 32-битный накопитель они восстанавливают отрицательное значение.
Транспорт
В качестве транспорта для Citeck WebAPI на данный момент используется HTTP, но в будущем возможны и другие протоколы.
FAQ
Как связан Records API и Citeck WebAPI?
RecordsAPI использует Citeck WebAPI в качестве транспорта для общения между микросервисами.