Давайте продолжим цикл постов про API.
Поговорим про версионирование – очень актуальная тема, т.к. когда API только запустили, про версии обычно не думают, а зачем? Всё же работает))
Проблемы начинаются позже. Когда приходит задача «чуть-чуть доработать»:
• добавить новое поле
• изменить формат ответа
• переименовать параметр
• поменять логику расчёта
И на первый взгляд кажется, что это же небольшое изменение, давайте сделаем.
А для клиента это сломанный интеграционный контракт.
На моём опыте здесь есть ключевая мысль, которую часто недооценивают: API – это публичное обещание
Если вы один раз отдали структуру ответа, кто-то уже на неё завязался. И любое изменение = потенциальный инцидент.
Что считается реально опасным?
⏺изменили тип данных (string → number)
⏺удалили или переименовали поле
⏺поменяли обязательность поля
⏺изменили бизнес-логику (например, статус считается по-другому)
Даже если внутри всё стало лучше, снаружи это может всё сломать.
Поделюсь, как я обычно подхожу к этому:
1. Версию закладываю сразу
/api/v1/orders
Даже если кажется, что нам это не скоро понадобится)
2. Разделяю изменения
• добавление поля: можно в текущей версии
• изменение логики / структуры: новая версия
3. Фиксирую правило для команды
Старая версия живёт, пока есть потребители – это очень важно.
Потому что самая частая ошибка: давайте просто обновим v1!
В общем мой посыл в том, что надо думать не просто «как улучшить API», но при этом думать, как не сломать тех, кто уже с ним работает.
И если говорить про «хорошее API» – это то, которое можно безопасно развивать со временем.
Пользуйтесь в работе, к этому приходишь не сразу, а через собственно набитые шишки)