API-first для внутренних систем: зачем это важно до того, как их стало много
Строить внутренние инструменты и системы с подходом API-first - это не лишняя работа. Это дисциплина, которая предотвращает интеграционный хаос, который большинство компаний потом годами распутывают.
API-first дизайн ассоциируется с продуктами, обращёнными наружу: платформами, SaaS-инструментами, экосистемами для разработчиков. Эта дисциплина значительно реже применяется к внутренним системам - кастомным инструментам, внутренним порталам и операционному ПО, которое большинство компаний строит или конфигурирует. Это ошибка, и её цена проявляется несколько лет спустя.
Типичный результат игнорирования API-first внутри компании - набор систем, которые могут разговаривать друг с другом только через хрупкие точечные интеграции, файловые выгрузки или ручной повторный ввод данных. Когда нужно подключить новую систему, выясняется, что каждую интеграцию приходится строить с нуля. Когда нужно заменить одну систему, оказывается, что её интерфейсы не определены, и каждый потребитель закодировал предположения о её внутреннем устройстве.
Что API-first означает на практике
API-first не означает строить REST API для всего прежде, чем строить что-либо ещё. Это означает принять решение, на раннем этапе, что каждая система предоставляет свои возможности через определённый, версионированный интерфейс - и что ничто за пределами системы не обходит этот интерфейс для прямого чтения или записи данных.
Интерфейс может быть REST API, очередью сообщений, протоколом файлового обмена или потоком событий - в зависимости от того, что подходит для задачи. Важно, чтобы он был явным, документированным и рассматривался как контракт.
Наиболее распространённое нарушение, которое я вижу, - прямой доступ к базам данных между системами. Одна система пишет в таблицу базы данных. Другая система читает из той же таблицы. Контракта нет. Когда первая система меняет схему, вторая ломается без предупреждения. Умножьте это на пять или десять систем за несколько лет - и вы получаете классический интеграционный кошмар.
Внутренние платформы, которые делают это правильно
Компании, избегающие этой проблемы, разделяют один паттерн. Они рассматривают каждую внутреннюю систему как сервис с владельцем. Владелец контролирует интерфейс и отвечает за обратную совместимость при его изменении. Потребители декларируют зависимость от интерфейса, а не от внутреннего устройства системы. И есть лёгкий процесс для согласования ломающих изменений, а не обнаружения их в продакшне.
Для этого не нужна формальная платформа управления API. Для небольших команд достаточно OpenAPI-спецификации, закомиченной в репозиторий, и нормы о том, что никто не читает базу данных напрямую. Суть - в дисциплине, а не в инструментарии.
Почему инвестиция оправдана даже для небольших внутренних инструментов
Чаще всего мне возражают, что небольшие внутренние инструменты не оправдывают издержки определения API. Мой опыт говорит об обратном. Небольшие внутренние инструменты имеют тенденцию расти. Они получают больше пользователей, больше интеграций, больше данных. Стоимость ретрофита API на инструмент, построенный без него, всегда выше, чем встраивание его с самого начала.
Второй аргумент: вы покупаете будущую гибкость. Если у каждой внутренней системы есть определённый интерфейс, вы можете заменить реализацию - базу данных, фреймворк, хостинг - не меняя каждого потребителя. На горизонте пяти лет это значимая свобода.
Практическая отправная точка
Если вы строите что-то новое, минимальное жизнеспособное обязательство таково: определите интерфейс до того, как начнёте строить реализацию. Опишите, что поступает на вход, что выходит, каковы случаи ошибок и кто является владельцем. Храните это определение в системе контроля версий. Не допускайте прямого доступа к базе данных извне системы.
Если вы работаете с существующими системами, начните с картирования незаявленных зависимостей. Какие системы читают какие базы данных напрямую? Какие интеграции не имеют документированного контракта? Сделать неявное явным - первый шаг к замене его чем-то поддерживаемым.