Конвенция для заголовка ответа HTTP для уведомления клиентов устаревшего API

Ответ 1

Я бы ничего не изменил в коде состояния, чтобы быть обратно совместимым. Я бы добавил в ответ заголовок "Предупреждение":

Warning: 299 - "Deprecated API"

Вы также можете указать "-" с "Агентом", который выдает предупреждение, и быть более явным в тексте предупреждения:

Warning: 299 api.blazingFrog.com "Deprecated API : use betterapi.blazingFrog.com instead. Old API maintained until 2015-06-02"

Предупреждающий заголовок указан здесь: https://tools.ietf.org/html/rfc7234#section-5.5. Предупреждающий код 299 является общим, "Устаревший" не является стандартным.

Вы должны сказать своим клиентам API, чтобы они регистрировали HTTP-предупреждения и отслеживали их.

Я никогда не использовал его до сих пор, но когда моя компания будет более зрелой в Rest API, я ее интегрирую.

Ответ 2

Вы можете использовать 410 (Gone).

Здесь как W3C Определения кода состояния описывают это:

410 (ушел)

Запрошенный ресурс больше недоступен на сервере, и нет адрес пересылки известен. Ожидается, что это условие будет считается постоянным. Клиенты с возможностями редактирования ссылок СЛЕДУЕТ удалите ссылки на Request-URI после утверждения пользователем. Если сервер не знает или не имеет возможности определить, независимо от того, условие является постоянным, код состояния 404 (не найден) ДОЛЖЕН быть используется вместо этого. Этот ответ можно кэшировать, если не указано иное.

Ответ 410 предназначен в первую очередь для того, чтобы помочь с уведомлением получателя о том, что ресурс намеренно недоступны и что владельцы серверов желают, чтобы удаленные ссылки на этот ресурс будут удалены. Такое событие является общим для с ограниченным сроком, рекламные услуги и ресурсы, принадлежащие люди больше не работают на сервере. Это не необходимо отметить все постоянно недоступные ресурсы как "ушедшие" или для сохранения метки в течение какого-либо промежутка времени - это остается по усмотрению владельца сервера.

Ответ 3

Я бы/отправился с 301 (перемещался постоянно). Коды серии 300 должны сообщать клиенту, что у них есть действие.

Ответ 4

Я бы рекомендовал ответ 207 Multi-Status, указывающий, что это успешный ответ, но он также потенциально имеет второй устаревший статус.

Ответ 5

Существует поле заголовка HTTP с именем Sunset которое предназначено для оповещения о предстоящем устаревании ресурса. https://tools.ietf.org/html/draft-wilde-sunset-header находится на последних этапах становления RFC. В идеале, ваш API должен задокументировать, что он будет использовать Sunset, чтобы клиенты могли его искать и действовать, если захотят.

Ответ 6

Уточнение @dret ответа. Есть два соответствующих HTTP заголовков для устаревания: Deprecation (https://tools.ietf.org/html/draft-dalal-deprecation-header-00) и Sunset.

Чтобы проинформировать пользователей о запланированном устаревании, следует использовать HTTP-заголовок Deprecation. Это указывает на то, что конечная точка будет удалена в будущем. Это также позволяет вам указать дату, когда это было объявлено, и описать альтернативные ресурсы.

Чтобы проинформировать пользователей о запланированной дате закрытия устаревшего ресурса, заголовок Sunset следует использовать в дополнение к заголовку Deprecation. Это описано в разделе № 5 https://tools.ietf.org/html/draft-dalal-deprecation-header-00#section-5.

Черновик № 11 https://tools.ietf.org/html/draft-wilde-sunset-header-11 заголовка Sunset разъясняет этот аспект в разделе 1.4 https://tools.ietf.org/html/draft- wilde-sunset-header-11 # section-1.4.