Кратко

  • RFC 9745, опубликованный в марте 2025 года, определил поле Deprecation с датой в синтаксисе Structured Fields. Само объявление не меняет работу ресурса.
  • Связь Link с отношением deprecation ведёт к политике или инструкции по переезду и может появиться раньше даты. RFC 8594 от 2019 года отвёл Sunset для ожидаемого прекращения ответов.
  • Уведомление относится прежде всего к ресурсу данного ответа. Чтобы охватить целую API, поставщик должен описать правило расширения области действия.

Рабочий ответ с часами на выходе

У интерфейса бывает длинный уход. Мониторинг сообщает, что всё исправно, запросы проходят, данные доступны. Оператор при этом уже выбрал замену и хочет, чтобы новые проекты не привязывались к старому пути. Объявление на отдельной странице может не попасть в руки разработчику, который смотрит только на ответы сервера. Если предупреждение приходит с первой ошибкой, время для безопасной миграции исчезает.

RFC 9745 перенёс сигнал в HTTP-ответ. Deprecation сообщает дату, когда указанный ответом ресурс будет или уже был объявлен устаревающим. Значение записывается как Date по правилам Structured Fields. Пример Deprecation: @1688169599 указывает 30 июня 2023 года, 23:59:59 UTC. Будущая дата обозначает начало периода, прошедшая — что этот период уже наступил.

Ресурс при этом продолжает выполнять прежнюю работу. RFC прямо говорит, что объявление не меняет его поведения. Одна и та же успешная операция несёт сообщение о том, что создавать новую зависимость стало рискованной тратой времени. Поставщик может продолжать обслуживать старых клиентов и одновременно менять направление для будущих. Клиентская команда должна читать оба сигнала.

Область действия определяется аккуратно. Поле относится к ресурсу, с которым связан ответ. Оператор может иметь в виду всю API или множество маршрутов, но обязан объяснить, как объявление на одном адресе распространяется на другие. Один заголовок подтверждает решение по одному ресурсу; большой план находится в правилах поставщика.

Инструкция может прийти до срока

RFC 9745 зарегистрировал также отношение deprecation для Link. Сервер может направить разработчика к документу о замене, порядке предупреждений и миграции. Такой указатель разрешено отправлять до появления самого поля с датой. У клиента появляется возможность заранее узнать политику, пока ресурс ещё не объявлен устаревающим.

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

У двух этапов разные даты

RFC 8594, вышедший в мае 2019 года, определил Sunset — время, когда ресурс, как ожидается, перестанет отвечать. Поле использует обычную дату HTTP. Deprecation говорит о более раннем решении: ресурс ещё действует, но перестаёт быть рекомендуемой основой для новых зависимостей. Одни часы нужны для архитектурного выбора, другие — для ожидания доступности.

RFC 9745 допускает совместное использование и запрещает ставить Sunset раньше Deprecation. В примере первое объявление приходится на 30 июня 2023 года, ожидаемый уход — на 30 июня 2024-го. Обратный порядок означал бы закрытие до предупреждения о начале отступления. Синтаксис отражает разное происхождение полей: дата с @ у нового Structured Fields и традиционная HTTP-дата у Sunset.

Оператор объявляет расписание; его ценность определяется ясной областью действия, работающей заменой и выполнением обещанных шагов. Чтобы назвать конкретные внедрения, нужны датированные сохранённые ответы сервисов. Нормативная история уже показывает новшество: живой интерфейс способен передавать собственное объявление о предстоящем уходе в успешных ответах.