Опублікований API - контракт з клієнтами, яких ви не контролюєте: мобільні застосунки старих версій, інтеграції партнерів. Їх не можна оновити одночасно з сервером.
Сумісні зміни (можна будь-коли):
- додати новий ендпоінт;
- додати необов'язкове поле в запит;
- додати поле у відповідь (клієнти мають ігнорувати невідомі поля - це варто прописати в документації);
- додати нове значення в перелік - обережно: клієнт зі строгою перевіркою enum може зламатися.
Несумісні (ламаючі): видалити чи перейменувати поле, змінити тип чи формат, зробити поле обов'язковим, змінити зміст коду відповіді, змінити поведінку за замовчуванням.
Версіонування для ламаючих змін:
- в URL -
/v1/orders,/v2/orders: найпростіше й найпомітніше; - в заголовку -
Accept: application/vnd.example.v2+jsonабо власний заголовок; - датою - як Stripe (
Stripe-Version: 2025-03-31): кожен клієнт закріплений на версії API на момент інтеграції, а сервер перетворює відповіді для старих версій.
Плавне виведення старого:
- Оголосити застарілість у документації й журналі змін.
- Додати заголовки:
Deprecation(RFC 9745) - що ресурс застарів,Sunset(RFC 8594) - дата, після якої він перестане працювати, іLinkна документацію з міграцією. - Моніторити використання старої версії за клієнтами й писати тим, хто ще на ній.
- Вимикати лише після дати й коли трафік зійшов нанівець.
Найкращий спосіб уникнути ламаючих змін - продумане проєктування: обгортки-об'єкти замість голих масивів у відповідях (до них можна додати поля), ідентифікатори-рядки, явні формати дат і грошей.
