Як спланувати міграцію після breaking change в API

Що перевірити спочатку

Почніть з короткого списку фактів:

1. Який саме контракт змінився: endpoint, schema, header, auth flow чи формат помилки.
2. Чи зачіпає зміна тільки один шлях, чи декілька call site.
3. Чи є тимчасова сумісність зі старою версією.
4. Чи можна додати fallback без змін у клієнтському коді.

Якщо цього не зробити, легко витратити час на не той фрагмент системи. Наприклад, зміна може виглядати як “нова версія SDK”, але реальна проблема сидить у серіалізації запиту або в перевірці токена.

Побудуйте map впливу

Не намагайтеся одразу “виправити все”. Спочатку складіть impact map:

• де викликається старий API;
• які тести покривають цей шлях;
• які дані можуть зламатися тихо, без явної помилки;
• які залежності треба оновити разом із цим контрактом.

Цей крок особливо важливий, якщо зміна прийшла через транзитивну залежність або через сервіс, який ви не контролюєте напряму.

Виберіть безпечний шлях

Після того як зрозуміли масштаб, виберіть один із чотирьох варіантів:

• shim або адаптер, якщо треба тимчасово перекласти старий формат у новий;
• feature flag, якщо зміна ризикована й потрібен контрольований запуск;
• dual path, якщо треба підтримати стару і нову поведінку паралельно;
• відкладений rollout, якщо сумісність ще не підтверджена.

Важливо не плутати “можна запустити” з “можна спокійно підтримувати”. Якщо новий контракт ще не покритий тестами, безпечніше спочатку додати захист, а вже потім викочувати зміни.

Практичний чекліст

• Описати зміну простими словами: що нове і що стало несумісним.
• Знайти всі call site, які залежать від старого контракту.
• Додати або оновити тести на позитивний і негативний сценарій.
• Перевірити, чи працює fallback у разі часткової деградації.
• Викотити зміни поетапно й спостерігати за помилками, latency або retry-rate.

Типові помилки

Найчастіше команди спотикаються об три речі:

1. Дивляться тільки на документацію, але не шукають реальні call site.
2. Перевіряють happy path, але не перевіряють failure mode.
3. Залишають rollout без резервного плану.

Саме тут корисний AI-помічник: не як заміна інженерному рішенню, а як спосіб швидко перетворити зміну на структурований план.

Далі почитати

• Semantic Versioning 2.0.0
• Google API Design Guide
• OpenAPI Specification

Що можна зробити далі

Якщо у вас уже є breaking change у черзі на реліз, почніть з короткого інвентаря: що змінилося, де це використано, який fallback доступний і як ви відкочуєтеся, якщо тест не пройде.