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