OpenAPI | AsyncAPI

Когда ты думаешь, что API - это только REST и что подобные ручки «GET /users» - это пик инженерии, внезапно врывается AsyncAPI.

Недавно на собесе говорили про openAPI и asyncAPI. Год назад пробовали asyncAPI затащить на проект. Пора поделиться, что это такое и зачем аналитику.

🟢Если Swagger (OpenAPI) / вторая ссылка - это про «запрос-ответ», обязательно посмотри пример по ссылке openAPI aviasales публичного API, то AsyncAPI - это про сообщения, события и стримы.

Не «ты мне запрос, я тебе ответ», а «клиент подписался и теперь получает обновления, даже если сам ничего не спрашивал».

Зашел в чат с другом, а тебе сыпятся сообщения на экране без запросов. Сидишь на веб-ресурсе и приходят уведомления один за другим.

Применяется это добро для систем с Kafka, MQTT, WebSocket, AMQP, и вообще везде, где все крутится вокруг топиков/событий, а не HTTP-запросов.

➡️Почему аналитикам это должно быть интересно?

Потому что с аналитиков просят знать работу брокеров сообщений, проектировать API событий, и теперь ты, как системный аналитик, можешь разобраться, как описывать событийные интерфейсы, а не только REST HTTP.

🔗 Типичные сценарии:

🚕 в телематике «машина отправила координаты» — событие;

💳 в платежах «транзакция прошла» — событие;

📦 в логистике «посылка изменила статус» — тоже событие.

И всё это можно задокументировать. Визуально. В Swagger Editor, только теперь не openapi: 3.0.0, а asyncapi: 3.0.0. По ссылке спека со скрина в посте)