Практика1

1. API версии 2.0: как грамотно внедрять обновления без потери пользователей

2. Обратная совместимость.

• Обратная совместимость (backward compatibility) — свойство API,
при котором обновление не ломает существующих клиентов.
Клиент, написанный для v1, продолжает работать после
обновления сервера.
• Пользователи API теряют доход каждый раз, когда им приходится
обновлять свои приложения, чтобы соответствовать новому
контракту API. Слишком много критических изменений за
короткий период, скорее всего, побудит пользователей API начать
искать более стабильный API.

3. Документирование всех версий API и публикование журналов изменений.

• Некоторые компании предоставляют документацию только для
последней версии API, а это значит, что клиенты, использующие
более старые версии API, не смогут найти необходимую
информацию.
• Список изменений, описывающий все изменения в каждом
новом релизе API, является одним из важнейших справочных
документов для пользователей API. Он позволяет им убедиться,
что изменения не окажут негативного влияния на их приложение,
и принять решение о необходимости обновления.

4. Ломающие и безопасные изменения.

• Ломающие изменения — любое изменение, которое может
вызвать ошибку у существующего клиента:
Изменение
Почему ломает
Удаление эндпоинта
Клиент получит 404
Удаление поля из ответа
Клиент обращается к
несуществующему полю
Переименование поля
Старое имя больше не существует
Изменение типа поля (string → number) Клиент парсит неправильно
Новый обязательный параметр
запроса
Старые запросы без этого параметра →
400
Изменение URL эндпоинта
Старый URL → 404
Изменение формата ошибок
Клиентский обработчик ошибок
ломается
Изменение HTTP-статусов
Клиент обрабатывает другой код

5. Ломающие и безопасные изменения.

• Безопасные изменения:
Изменение
Почему безопасно
Добавление нового поля в ответ
Клиент игнорирует неизвестные поля
Добавление нового эндпоинта
Старые эндпоинты работают
Добавление необязательного
параметра
Старые запросы проходят валидацию
Расширение enum новыми значениями Безопасно, если клиент обрабатывает
неизвестные значения
Увеличение лимитов (max length, rate
limit)
Более мягкие ограничения не ломают
Улучшение текста ошибок
Если клиент парсит код ошибки, а не
текст

6. Стратегии версионирования

• 1. Версия в URL (URL Path Versioning)
• Плюсы: Максимально наглядно; Легко тестировать в браузере;
Просто роутить (Nginx, API Gateway); Легко кэшировать (CDN)
• Минусы: URL меняется при смене версии; Дублирование кода
между версиями; Не «чистый» REST (версия — не ресурс)

7. Стратегии версионирования

• 2. Версия в заголовке (Header Versioning)
• Плюсы: URL не меняется; «Чистый» REST; Гибко: можно
версионировать отдельные ресурсы
• Минусы: Нельзя протестировать в браузере; Сложнее
кэшировать; Менее очевидно для клиентов

8. Стратегии версионирования

• 3. Версия в Query Parameter
• Плюсы: Простая реализация; Легко тестировать; Можно задать
версию по умолчанию
• Минусы: Легко забыть параметр; Засоряет URL; Проблемы с
кэшированием

9. Deprecation: правильный жизненный цикл

Когда старую версию пора отключать — делайте это плавно и
предсказуемо:
• Выпуск v2: Выпускайте новую версию. Старая (v1) продолжает
работать. Документация обновлена.
• Объявление deprecation: Добавьте заголовки Deprecation и Sunset
в ответы v1. Уведомите клиентов по email.

10. Deprecation: правильный жизненный цикл

• Период миграции: Обе версии работают. Мониторьте трафик v1.
Помогайте клиентам мигрировать.
• Напоминание: Повторное уведомление. Возвращайте Warningзаголовок с каждым ответом v1.
• Отключение v1: v1 возвращает 410 Gone с ссылкой на v2 и
инструкцией миграции.