Увійти Реєстрація
Вакансії
Вакансії Laravel Компанії Статистика
Підготовка
Як підготуватися Співбесіди Тестування Документація
Блог
Всі статті Серії
Екосистема
Пакети Ресурси Проєкти Інструменти Події Відео
Інше
Про нас Реклама

Як вести журнал змін API і автоматично ловити зміни, що ламають клієнтів?

Найнебезпечніші зміни API - ті, що непомітно ламають клієнтів: розробник «трохи покращив» ресурс, тести бекенду зелені, а інтеграція партнера падає. Захист - зробити зміни контракту видимими й перевірюваними.

Що ламає клієнтів (breaking changes):

  • видалення чи перейменування поля, ендпойнта, параметра;
  • зміна типу поля (число → рядок) чи формату (дата без поясу → з поясом);
  • новий обов'язковий параметр запиту чи поле тіла;
  • звуження допустимих значень (нові обмеження валідації, видалене значення enum);
  • зміна кодів статусу й формату помилок;
  • зміна поведінки за замовчуванням (сортування, розмір сторінки).

Що зазвичай безпечно: нові необов'язкові параметри, нові поля у відповіді, нові ендпойнти. «Зазвичай» - бо клієнт зі строгою десеріалізацією чи вичерпною перевіркою enum може зламатися й від нового значення. Це варто прямо прописати в політиці API: «клієнти мають ігнорувати невідомі поля й значення».

Автоматична перевірка в CI:

oasdiff breaking main-openapi.yaml branch-openapi.yaml --fail-on ERR
oasdiff changelog main-openapi.yaml branch-openapi.yaml
  • breaking - список змін, що ламають, з рівнями серйозності; збирання падає, якщо зміна не дозволена;
  • changelog - людиночитний перелік змін, який можна використати в описі pull request і журналі змін.

Специфікацію для порівняння беруть з основної гілки (згенеровану Scramble чи написану вручну) - так навіть «непомітні» зміни ресурсу Laravel стають видимими в рев'ю.

Журнал змін для споживачів:

  • дата й версія кожної зміни, групування: додано, змінено, застаріло, видалено;
  • посилання на документацію й інструкція з міграції для кожної зміни, що ламає;
  • оголошення заздалегідь: дата застарівання і дата видалення; для відповідей - заголовки Deprecation і Sunset;
  • канал повідомлень для інтеграторів (розсилка, RSS, сторінка статусу), а не лише сторінка, яку ніхто не відкриває.

Процес для змін, що ламають: нова версія ендпойнта чи поля, паралельна підтримка старого, моніторинг використання застарілого (логування запитів зі старими полями й версіями, щоб знати, хто ще залежить), повідомлення конкретним клієнтам, лише потім видалення.

Найкращий журнал змін - коротший: більшість змін, що ламають, можна замінити адитивними (нове поле поруч зі старим), і тоді клієнтам взагалі нічого не треба робити.

Докладніше в документації: oasdiff: порівняння OpenAPI-специфікацій

2

Схожі питання