Нейроны — природный пример API-centric дизайна

У нас тут была целая драма: мы решили полноценно перейти от бумажно-табличных стандартов описания API к нормальным человеческим OpenAPI и AsyncAPI. Если уже хорошо известный стандарт OpenAPI вызывал минимум вопросов и уже использовался некоторыми командами, то аналогичный стандарт для асинхронных взаимодействий стал основой этой самой драмы.

Итак, раньше в основном мы по старинке проектировали программный интерфейс и передавали разработчикам таблицы с описанием интеграционного взаимодействия. Т. е. два аналитика договаривались по некоему API на стыке их систем или сервисов, а затем каждый из них шёл в свою команду рассказывать и показывать, как он это понял. Заканчивалось всё тем, что иногда по нескольку недель и даже больше мы правили всякие весёлые баги, связанные с наименованием атрибутов и не только. Где uppercase, у кого lowercase, что с типами данных, в каком блоке должен быть атрибут, почему столько атрибутов с похожими названиями — всё это приводило к бесконечным циклам звонков, разглядывания спецификаций и реализаций. До драки не доходило, но пара случаев запомнилась.

Нам не хватало нормального единого формата, чтобы в первую очередь было детальное определение программного интерфейса, его обвязок, заголовков, координат на стендах (тестовых и промышленных) прямо в описании, и ключевое — чтобы всё это было машиночитаемым. Чтобы не выяснять отношений со смежными командами, а работать с единой для всех сторон спекой и генерировать код на её основании.

Разработчики поначалу очень не доверяли AsyncAPI на фоне OpenAPI (и для этого была очень конкретная причина), и именно в этом смысле началась ключевая часть драмы с новыми инженерными стандартами.