API как продукт: почему внутренние интеграции разваливаются
Как подход к внутренним API влияет на надёжность всей архитектуры и почему внутренний клиент заслуживает не меньшего уважения, чем внешний.
Когда компания строит публичный API для внешних партнёров, к нему относятся серьёзно. Есть документация, есть версионирование, есть процесс изменений. Ломать обратную совместимость - событие, которое согласовывается заранее.
Внутренние API живут по другим правилам. Их меняют, не предупреждая зависимые сервисы. Документацию не пишут, потому что "все свои". Версионирование не делают, потому что "успеем". В результате внутри компании воспроизводится та же хрупкость, от которой API и должны были защищать.
Я вижу это как один из самых распространённых источников операционных инцидентов в растущих технологических командах.
Что такое "API как продукт"
Это подход, при котором любой API - внутренний или внешний - проектируется и эксплуатируется так, как если бы у него были независимые клиенты, которых нельзя собрать в одной комнате и попросить переписать код к завтрашнему дню.
Практически это означает несколько вещей. Контракт API (структура запросов и ответов) зафиксирован и документирован. Изменения, нарушающие обратную совместимость, требуют явного решения и переходного периода. Клиенты API уведомляются об изменениях. Есть версионирование - хотя бы минимальное.
Звучит бюрократично. На самом деле это экономия времени: каждый инцидент из-за сломанной интеграции обходится дороже, чем минута на документацию контракта.
Почему внутренние API разваливаются
Три причины, которые я вижу постоянно.
Первая - "все свои". Когда один сервис пишет команда А, а другой команда Б, кажется, что можно просто позвонить и договориться. Это работает, пока команды маленькие и хорошо коммуницируют. При росте - перестаёт работать. Устная договорённость не масштабируется.
Вторая - нет ответственного за API. Когда у API нет явного владельца, его меняют все, кто касается соответствующего сервиса. Нет единой точки принятия решений о том, что допустимо изменять.
Третья - нет инструментов наблюдения. Если изменение API не приводит к немедленной видимой ошибке - проблема обнаруживается позже, в самый неудачный момент. Без автоматических контрактных тестов изменение проходит незамеченным.
Цена проблемы для бизнеса
Я видел ситуации, когда изменение одного внутреннего API укладывало несколько зависимых сервисов без предупреждения. Команды тратили день-два на поиск причины, потому что не было мониторинга и документации. Это прямые потери - и в деньгах, и в доверии между командами.
Более медленная версия той же проблемы: интеграции начинают обрастать "защитными" слоями кода, которые компенсируют нестабильность поставщика. Каждый такой слой - долг, который рано или поздно надо платить.
Минимальный стандарт
Для большинства команд не нужна сложная система управления API. Нужен минимальный стандарт:
- У каждого внутреннего API есть документация контракта - хотя бы схема запросов и ответов.
- У каждого API есть явный владелец - команда или человек, который принимает решения об изменениях.
- Breaking changes согласовываются с клиентами заранее, с временем на адаптацию.
- Есть хотя бы один интеграционный тест на критичных маршрутах.
Это не идеальная архитектура. Но это разница между системой, которую можно развивать, и системой, в которой каждое изменение - риск.