В этом материале
Уведомление deprecation сообщает о жизненном цикле интерфейса; фактические изменения поведения нужно версионировать и проверять отдельно.
Инвентаризировать наблюдаемый контракт
Публичный контракт inference API включает не только JSON поля, но и HTTP поведение, streaming-порядок, terminal states и семантику параметров. Изменение движка может затронуть этот слой даже без изменения пути endpoint. Перед выпуском сохраняют описание текущей версии и примеры клиентских сценариев. OpenAPI 3.1.1 помогает закрепить описание интерфейса, однако временные свойства SSE требуют дополнительных fixtures. Задача миграции — показать конкретный diff и последствия для потребителя. Фраза «API совместимый» без перечисления проверенных свойств не объясняет, почему старый парсер продолжит работать и какие изменения клиент должен обработать самостоятельно после обновления сервиса.
Разобрать типы изменений
Удаление обязательного поля, смена типа и новое значение enum могут нарушить клиентов с жёсткой валидацией. Добавление поля тоже не всегда безвредно, если клиент запрещает дополнительные свойства. Справочник объектов JSON Schema поясняет required и правила дополнительных свойств; эти настройки важны для оценки фактической совместимости. Отсутствие значения и null также различаются. Для каждого изменения записывают старый ответ, новый ответ и класс затронутых клиентов. Утверждение о совместимости должно относиться к определённой модели потребителя, а не ко всем возможным библиотекам. Семантическая смена значения при неизменном типе заслуживает такого же внимания, как заметное изменение схемы.
Использовать Deprecation по назначению
RFC 9745 определяет заголовок Deprecation и способы указать связанную информацию. Само уведомление не означает немедленного изменения поведения ресурса. Его следует отделять от даты фактического отключения и от конкретных инструкций переноса. В собственной политике описывают затронутую версию, причину, замену и канал документации. Это проектирование политики сервиса, а не утверждение о наличии такой практики у OpenRouter. Дата в уведомлении без объяснения области действия мало помогает клиенту. Если меняется только один режим streaming, формулировка должна позволять понять это без предположения, что прекращается весь API или каждая модель одновременно.
Прогнать обе стороны миграции
Небольшой корпус проверяет старый клиент со старым ответом, старый клиент с новым ответом и обновлённый клиент с обеими допустимыми формами. Для SSE отдельно проверяют добавленный кадр, изменение порядка и неизвестные поля. Fixtures содержат ожидаемые свойства, а не дословную генерацию. Диагностическая развилка начинается с места отказа: schema validation, разбор события или интерпретация terminal state. Затем определяют, нужна ли версия endpoint, период перекрытия или клиентская адаптация. Нельзя просто обновить golden-файлы и объявить миграцию успешной: это может удалить свидетельство несовместимости, ради выявления которой и запускалась проверка перед изменением публичного интерфейса.
Сохранить решение и область проверки
Артефакт выпуска содержит diff контракта, матрицу клиентов, утверждённые исключения, миграционный пример и условия отката. Полезны canary обновления модели и паспорт программного стека. Canary показывает поведение выбранной выборки, но не заменяет протокольную проверку редких сценариев. Успешная миграция означает прохождение перечисленных клиентов и fixtures в указанной среде. Она не даёт универсальной гарантии для неизвестных интеграций. После выпуска продолжают наблюдать ошибки разбора и распределение старых версий, не помещая идентификаторы пользователей в метрики. Это позволяет проверять последствия изменения по фактам, сохраняя понятные границы собственного обещания совместимости.