Версионирование API - это управление контрактами, а не техническая формальность
Почему у каждого API должна быть политика версионирования и что происходит с интеграциями, когда её нет.
Компании, которые активно строят интеграции между системами, рано или поздно сталкиваются с одной и той же ситуацией. Команда вносит изменение в один сервис - и где-то ломается что-то другое. Расследование занимает несколько часов, иногда дней. Виноватых формально нет: каждая сторона делала что-то разумное, но никто не думал о том, как это повлияет на остальных.
Корень проблемы почти всегда один - нет управления версиями API как контрактом.
Что такое контракт API
Когда система A вызывает систему B, она рассчитывает на определённое поведение. Конкретный формат запроса, конкретный формат ответа, конкретную семантику полей. Это и есть контракт.
Если B изменяется и контракт нарушается, A ломается. Если B изменяется незаметно, A ломается неожиданно - в любой момент, не обязательно сразу после изменения.
Версионирование - это способ сказать: "мы изменили поведение, но старый вариант ещё доступен под старым адресом". Это даёт потребителям API время адаптироваться, а не вынуждает их меняться немедленно.
Почему это важно для руководителя
Каждая неуправляемая зависимость между системами - это скрытый долг. Он не виден, пока всё работает. Но при каждом изменении в любой из систем кто-то должен держать в голове весь граф зависимостей и понимать, что сломается.
Чем больше интеграций, тем хрупче система. Тем дороже каждое изменение. Тем медленнее команда двигается.
Без политики версионирования API организация фактически говорит: "все наши интеграции - это один большой монолит, просто распределённый". Это хуже обычного монолита, потому что зависимости не видны статически.
Как выглядит минимальная дисциплина
Для большинства компаний не нужна сложная система. Достаточно нескольких принципов.
Первый: каждый API, которым пользуются другие системы или партнёры, имеет явный номер версии в адресе или заголовке. Это видно, прозрачно, и можно найти в коде.
Второй: есть политика поддержки - как долго живёт старая версия после выхода новой. Полгода, год - зависит от контекста. Но она есть и известна потребителям.
Третий: изменения, нарушающие контракт, выходят только в новой версии. Никаких "тихих" правок существующего поведения.
Четвёртый: есть реестр - список того, какие API существуют, кто их потребляет, и какова текущая версия. Это может быть простой таблицей, не обязательно дорогой платформой.
Где это ломается на практике
Самое частое место сбоя - это внутренние API между командами внутри одной компании. Кажется, что раз все свои, можно договориться на ходу. На практике это приводит к тому, что каждое обновление внутреннего сервиса требует координации и ломает что-то неожиданное.
Второе место - это интеграции с партнёрами и внешними системами. Здесь нарушение контракта может стоить не только времени разработки, но и репутации и денег.
Вопросы для проверки
Если вы хотите понять, насколько зрелая у вас дисциплина работы с API:
- Есть ли у ваших API явные версии?
- Есть ли реестр: кто что вызывает?
- Кто принимает решение о том, что изменение ломает контракт?
- Как долго вы поддерживаете старые версии?
- Как потребители узнают об изменениях?
Если ответов нет - у вас есть интеграции, но нет управления ими. При малом числе связей это терпимо. При десятке и больше - это уже источник операционной хрупкости.