𝟵 𝗔𝗣𝗜 𝗖𝗵𝗮𝗻𝗴𝗲𝘀 𝗧𝗵𝗮𝘁 𝗕𝗿𝗲𝗮𝗸 𝗬𝗼𝘂𝗿 𝗔𝗽𝗽

𝟵 𝗔𝗣𝗜 𝗖𝗵𝗮𝗻𝗴𝗲𝘀 𝗧𝗵𝗮𝘁 𝗕𝗿𝗲𝗮𝗸 𝗬𝗼𝘂𝗿 𝗔𝗽𝗽

«Ми нічого не зламали. Ми просто почистили відповідь».

Ці слова часто призводять до збоїв. Мобільний застосунок перестає працювати. Інтеграція з партнером повертає сміття. Ви змінили структуру даних, від яких залежать інші.

Небезпечні зміни часто виглядають як наведення ладу. Вони проходять перевірку коду та тести. Поломка стається в коді, якого ви не бачите.

Ось дев'ять змін, які здаються безпечними, але насправді такими не є.

• Перейменування полів Зміна userId на user_id задля узгодженості ламає клієнтів. Перейменування — це видалення та додавання. Саме видалення створює проблеми. Безпечний крок: Додайте нове поле. Залиште старе. Позначте його як застаріле (deprecate). Видаліть значно пізніше.

• Зробити поле необов'язковим Поле завжди було присутнє. Тепер воно іноді повертає null. Код клієнта падає, коли намагається його обробити. Безпечний крок: Ставтеся до «завжди наявної» наявності як до обіцянки. Якщо поле стає необов'язковим, використовуйте нову версію.

• Видалення невикористовуваних полів Ви не бачите, як ваші споживачі використовують ваші дані. «Невикористовуване» означає лише те, що воно не використовується вами. Безпечний крок: Виміряйте використання поля в продакшені, перш ніж щось видаляти.

• Звуження типів вхідних даних Зміна string на enum або number на integer ламає запити. Розширення вхідних даних є безпечним. Звуження — це критична зміна. Безпечний крок: Тільки розширюйте типи вхідних даних, які ви приймаєте. Звуження потребує нової версії.

• Зміна значень за замовчуванням Зміна значення за замовчуванням з false на true змінює поведінку без помилок. Це тихо ламає логіку. Безпечний крок: Ставтеся до зміни значення за замовчуванням як до критичної зміни.

• Додавання обов'язкових полів Додавання tenantId та створення умови його обов'язковості ламає кожного існуючого клієнта. Вони отримуватимуть помилку 400. Безпечний крок: Нові поля мають бути необов'язковими або потребувати нової версії.

• Зміна форматів помилок Зміна коду 400 на 422 або зміна тіла помилки ламає код обробки помилок. Безпечний крок: Формати помилок — це контракти. Версіонуйте їх так само, як і все інше.

• Зміна значень enum Перейменування "active" на "ACTIVE" ламає клієнтів. Видалення значення ламає клієнтів із суворою логікою. Безпечний крок: Значення enum — це назавжди. Додавайте їх обережно. Ніколи не перейменовуйте та не видаляйте їх без випуску нової мажорної версії.

• Зміна змісту даних Зміна формату дати з Unix seconds на ISO-8601 або зміна пагінації з offset на cursor ламає все. Різниця в схемі (schema diff) може навіть не зафіксувати це. Безпечний крок: Чітко фіксуйте формати. Порівнюйте реальні корисні навантаження (payloads), а не лише специфікацію.

Не покладайтеся на інтуїцію. Порівнюйте кожну зміну з контрактом продуктивного середовища у вашому CI. Людина може пропустити перейменоване поле. А diff-інструмент — ні.

Джерело: https://dev.to/deepaksatyam/9-api-changes-that-look-backwards-compatible-but-arent-1bk0