Всем привет!

Прочитал статью о том, как можно обойтись без OpenAPI при взаимодействии по REST API https://habr.com/ru/companies/magnit/articles/763952
Для тех кому лень читать - там предлагается использовать Java DTO. В целом подход интересный и рабочий. Но есть нюанс. Схема OpenAPI - внешний артефакт. Он лежит либо в git репозитории или API Studio от Swagger. Код по нему генерируется в каталоге сборки. Забыть обновится при выходе новой версии сложнее как раз из-за чёткого понимания того, что API - внешнее. Хотя конечно же можно )
Другое дело Java API. Это про сути ещё одна из десятков библиотек, подключенных к проекту. Версию библиотеки мы фиксируем как это принято при управлении зависимостями. Забыть о том, что это внешнее API, гораздо легче.
Я сейчас говорю не только про кейс, описанный в статье. Ещё есть вариант обмена данными через распределенный кэш, путём сериализации Java POJO объектов, встречал его на практике. А самый яркий антипаттерн при похожем подходе - обмен данными через БД. В этом случае как правило обмениваются скриптами БД, а не классами. Но идея похожа - зачем нам лишняя сущность в виде схемы, лишние преобразования, когда уже есть код. Или уже есть таблица в БД. Конечно, интеграция через БД стала антипаттерном в том числе и потому, что БД - это не только схема, но ещё и транзакции, блокировки, триггеры. Но главную причину я озвучил выше - каждая команда будет считать базу своей внутренней, забывая, что это API. Проблема психологическая, не техническая.
Итого: подход интересный, имеет права на жизнь (я про обмен jar-никами, не про интеграцию через БД), но требует дисциплины. Или автоматизации на этапе CI, позволяющей не надеятся на человеческий фактор.

P.S. Как говорится, не OpenAPI единым - есть ещё Protobuf, GraphQL, xsd наконец. Но самый распространённый - OpenAPI, поэтому везде упоминается он.

#api #OpenAPI #integration

OpenAPI для асинхрона - а, пожалуйста

Я думаю все знают, как описать API для REST взаимодействия. OpenAPI давно уже стал стандартом.

Перечислю его основные плюсы:
1) широкое распространение
2) автоматическая генерация документации
3) онлайн редактор Swagger UI
4) генерация серверного и клиентского кода по схеме
5) стандарт покрывает не только собственно содержимое body сообщения, но и описывает всю схему взаимодействия: параметры URL, заголовки включая куки, коды ошибок. Даже адреса серверов, хотя как по мне - это спорный момент.

Но асинхронное взаимодействие, ака Event-Driven Architecture: Kafka, MQ.. - имеют свои особенности. Как минимум это:
1) нет понятия запрос-ответ, вместо этого обмен идет сообщениями
2) другой набор протоколов (хотя http есть и там, и там)
3) другая терминология - есть каналы (топик или очередь), у канала есть свои характеристики
4) в любом взаимодействии нужно описать 3 участников: producer, канал, consumer.

Поэтому появился AsyncAPI. Он достаточно сильно похож на OpenAPI:
1) тот же YAML,
2) похожи (с точностью до сказанного выше) основные блоки, из которых строится API - Info, Servers, Tags, Schemas...
Видно чем вдохновлялись авторы) Как сказано на официальном сайте: "Part of this content has been taken from the great work done by the folks at the OpenAPI Initiative."
И это хорошо.

Стандарт молодой, но уже стал стандартом ))) да, тавтология) Имеет все те же преимущества, что и OpenAPI - см. начало поста.
Вот неплохая статья с примером https://bigdataschool.ru/blog/asyncapi-specification-for-kafka-practical-example.html

Поэтому настоятельно рекомендую для использования.

#api #openapi #asyncapi