API и контракты

Платформа предоставляет несколько интерфейсов взаимодействия для разных типов клиентов и систем.

Типы интерфейсов

1. Internal Kafka RPC (Request-Reply)

Основной способ межсервисного взаимодействия. Позволяет достичь высокой отказоустойчивости и асинхронности.

• Топики: Описаны в Каталоге топиков.
• Формат: Protobuf + EventEnvelope.

2. Internal gRPC API (Sync)

Используется в исключительных случаях, где требуется мгновенный ответ (например, синхронные проверки при аутентификации).

• Порт по умолчанию: 50051.
• Определение: Описано в .proto файлах в packages/contracts/proto/maniton.

3. External REST/GraphQL API (Gateway)

Единая точка входа для фронтенд-приложений и внешних партнеров.

• Авторизация: JWT токены (Keycloak).
• Документация: Swagger/OpenAPI.

4. Kafka Event Stream

Асинхронный интерфейс для интеграции и реактивной обработки данных.

• Формат: Protobuf.
• Топики: Смотрите Каталог топиков.

Работа с контрактами

Мы используем Buf для управления Protobuf-контрактами.

Генерация кода

Чтобы сгенерировать TS или Go код из контрактов, выполните:

bun buf:generate

Правила изменения

• Никогда не меняйте номера полей.
• Используйте reserved для удаленных полей.
• Новые поля должны быть опциональными или иметь значение по умолчанию.

Каталог Kafka событий →