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

86

Я обновляю наши конечные точки REST API и хочу уведомить клиентов, когда они вызывают конечную точку, которую не рекомендуется использовать.
Какой заголовок я должен использовать в ответе с сообщением типа «Эта версия API устарела, пожалуйста, обратитесь к последней документации, чтобы обновить свои конечные точки»

rest http http-status-codes deprecation-warning Пылающая лягушка
источник

Ответы:

75

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

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, я интегрирую его.

Изменить (2019-04-25): как отметил @Harry Wood, заголовок предупреждения находится в главе документации, связанной с кешированием. Однако RFC ясенWarnings can be used for other purposes, both cache-related and otherwise.

Если вы предпочитаете альтернативный метод, этот черновик https://tools.ietf.org/html/draft-dalal-deprecation-header-00 предлагает новый заголовок «Устарело».

BenC
источник
1
Дата предупреждения в конце значения предупреждения здесь не имеет смысла, и лучше не использовать его, иначе вы рискуете запутать клиентов: «Если получатель. . . получает дату-предупреждения, которая отличается от Dateзначения в том же сообщении, получатель ДОЛЖЕН исключить значение-предупреждения. . . до . . . используя сообщение ».
Василий Фаронов
Если вы включаете в предупредите-дату, он должен быть отформатирован таким же образом , как и Dateзаголовок: "Thu, 02 Apr 2015 12:25:32 GMT".
Василий Фаронов
@VasiliyFaronov: вы правы, потому что в этом случае (устаревший API) это предупреждающее сообщение всегда будет правдой в будущем. Поэтому, если ответ (с предупреждающим сообщением) отправляется кешем в прокси-сервере и дата сообщения отличается, предупреждение будет проигнорировано, хотя оно останется действительным. Редактирую ответ
BenC 06
Разве этот заголовок «предупреждение» не связан с кешированием? Я имею в виду, что в вашей ссылке документации упоминается кеширование, но также весь этот документ RFC, похоже, связан с кешированием. Но Warningзаголовок действительно хорош как место для свободного текста, чтобы описать устаревание. Эти Deprecationи Sunsetзаголовки , указанные в других ответах, казалось бы, вытекая стандартным решением для описания устаревания в туже потенциально более машиночитаемом способом.
Гарри Вуд
1
Warningзаголовок не относится только к кешам. Первое предложение в Warningразделе - «Предупреждения могут использоваться для других целей, как связанных с кешем, так и в иных целях».
Челеби Мурат
37

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

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

410 (ушел)

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

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

Эмануил Русев
источник
36
Проблема с 410 в том , что он не соответствует «чтобы быть устаревшим» требование ... Он отлично работает после исчезновения API, но не то, что он будет уйти в будущем .
Жюльен Женесту,
3
Если вы
вернете
4
410 Goneэто не об устаревании, а о методах, которые больше не доступны. Как сказал @BenC, лучший способ - использовать заголовок Warning
sempasha
2
Это может быть следующий этап устаревшего API
Шиплу Мокаддим
16

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

u07ch
источник
4
Вероятно, это то, что я буду использовать после фактического удаления конечной точки, но я хочу дать им возможность получать уведомления в течение некоторого времени (при условии, что они будут смотреть на заголовки HTTP в ответе), чтобы они могли внести необходимые изменения в их конец.
BlazingFrog
2
На самом деле нет статуса для переезда. 302 (Запрошенный ресурс временно находится в другом месте, но его все еще можно найти по запрошенному URI.) ...
u07ch
1
Я ищу не статус, а "стандартный" заголовок, который нужно добавить к ответу.
BlazingFrog
1
Для такого ответа нет стандартного заголовка. Вы должны создать собственный заголовок и описать его в документации по собственному API.
Брайан Келли
Я думаю, что любой код ответа> = 300 должен что-то сломать. 299 позволит клиентам поддерживать свое приложение в рабочем состоянии до тех пор, пока API не будет отключен, пока они вносят необходимые изменения.
devlord
6

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

typeoneerror
источник
1
Интересно. Я не знал об этом, но я думаю, что на практике есть большая опасность, что вы внесете критическое изменение для некоторых клиентов, переключившись на другой код ответа, даже если он все еще находится в диапазоне 200. Думаю, вы могли бы слегка увеличить давление. Начните с Deprecationзаголовка (который, к сожалению, клиенты, скорее всего, проигнорируют), затем используйте этот код 207, затем переместите 301, а затем, наконец, пропадет 410!
Гарри Вуд
4

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

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

Чтобы проинформировать пользователей о планируемой дате прекращения использования устаревшего ресурса, 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 # раздел-1.4 .

sdatspun2
источник
3

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

дрет
источник