Почему это реальный кейс
В микросервисной архитектуре у разных клиентов (мобильное приложение, веб-версия, интеграции партнёров) могут быть разные графики обновления. Если разработчики API меняют контракт (удаляют поле
name, разбивают его на firstName и lastName) и сразу выключают старую версию, клиенты, которые не обновились, ломаются. Это классическая проблема breaking change.Что должен был сделать аналитик
Зафиксировать требование обратной совместимости: новая версия API не должна удалять поля, которые использовались в старой. Вместо этого добавлять новые поля (
firstName, lastName) и сохранять старое поле name (можно вычислять как конкатенацию).Внедрить grace period: объявить дату устаревания (deprecation) старой версии, например, через 6 месяцев. Всё это время обе версии работают параллельно. В ответах старой версии добавить заголовок
Deprecation: true и ссылку на документацию новой версии.План миграции: клиенты (мобильное приложение) должны перейти на новую версию в течение grace period. Только после того, как все клиенты переключились, старую версию можно отключать.
Мониторинг: отслеживать, какие клиенты всё ещё используют старую версию, и напоминать им о необходимости обновления.
Почему не подходят другие варианты
A (увеличить срок предупреждения) — без политики параллельной работы и обратной совместимости всё равно ломает клиентов в момент отключения.
C (переписать мобильное приложение до отключения) — на практике часто невозможно, так как обновление зависит от пользователей.
D (откатить API) — временное решение, не решающее проблему в будущем.
Реальный пример
GitHub API версионирует через даты (например,
2022-11-28). Старые версии поддерживаются минимум 6 месяцев после объявления deprecation. В заголовках ответа присылают Sunset с датой отключения. Это даёт клиентам время на миграцию.Вывод для аналитика
При проектировании API всегда закладывайте:
Параллельную работу нескольких версий.
Минимальный срок поддержки старой версии (например, 6–12 месяцев).
Обратную совместимость: добавляйте поля, не удаляйте и не меняйте типы существующих.
Механизм уведомления клиентов о deprecation (заголовки, email, документация).