Вопрос по rest, deprecation-warning, http-status-codes, http – Соглашение для заголовка ответа HTTP, чтобы уведомить клиентов об устаревшем API

67

m обновление наших конечных точек API REST, и я хочу уведомить клиентов, когда они вызывают устаревшую конечную точку.

Какой заголовок я должен использовать в ответе с сообщением в строке "Эта версия API устарела, пожалуйста, обратитесь к последней документации, чтобы обновить ваши конечные точки "

Ваш Ответ

5   ответов
2

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

5

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

Интересно. Я не'не знаю об этом, но я думаю, что на практикеСильная опасность для васЯ буду вносить решающее изменение длянемного клиенты, переключаясь на другой код ответа, даже если онвсе еще в диапазоне 200. Я полагаю, вы могли бы слегка смягчить давление. Начните сDeprecation заголовок (который клиенты, вероятно, будут игнорировать, к сожалению), затем позже используйте этот код 207, затем 301 переместили, а затем 410 ушли! Harry Wood
11

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

Я думаю, что любой код ответа>= 300 должен ломать вещи. 299 позволит клиентам поддерживать свое приложение до тех пор, пока API не будет отключен, пока они вносят необходимые изменения. devlord
Я не ищу статус, но для "стандарт» заголовок, чтобы добавить к ответу. BlazingFrog
Там'Нет стандартного заголовка для такого рода ответа. Вы должны создать свой собственный заголовок и описать его в своем собственном API 'документация Brian Kelly
Код состояния является частью вашего REST API. Поскольку API является соглашением между клиентом и сервисом, в первую очередь вы должны предупреждать клиентов о будущих критических изменениях. Некоторые клиенты могут не поддерживать перенаправления, поэтому после получения301 Moved Permanently они предполагают, что запрос не выполнен из-за неизвестного кода ответа (они ожидают200 Success например). Другими словами - вы рискуете нарушить совместимость с клиентами, изменив код статуса ответа. Как сказал @BenC, лучше использоватьЗаголовок предупреждения уведомить клиентов. sempasha
61

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

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, Warn-код 299 является общим, "Устаревшее» не является стандартным

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

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

@VasiliyFaronov: тыверно, потому что в этом случае (устаревший API) это предупреждающее сообщение всегда будет верным в будущем. Таким образом, если ответ (с предупреждающим сообщением) отправляется кешем в прокси и дата сообщения отличается, предупреждение будет проигнорировано, тогда как оно все еще будет действительным. Я редактирую ответ BenC
Если вы указали дату предупреждения, она должна быть отформатирована так же, какDate заголовок:"Thu, 02 Apr 2015 12:25:32 GMT" Vasiliy Faronov
Isn»т это "предупреждение" заголовок, связанный с кэшированием, хотя? Я имею в виду, что в вашей ссылке на документацию упоминается кэширование, но также и весь документ RFC, похоже, связан с кэшированием. НоWarning Заголовок выглядит хорошо как место свободного текста для описания устаревания.Deprecation а такжеSunset Заголовки, упомянутые в других ответах, представляются новым стандартным решением для описания устаревания более жестким, более машиночитаемым способом. Harry Wood
Вы'прав @HarryWood, я этого не видел. Основная глава называетсяЭтот раздел определяет синтаксис и семантику полей заголовка HTTP / 1.1, связанных с кэшированием. " Тем не менее, это единственный стандарт сегодня. Ты упомянулtools.ietf.org/html/draft-dalal-deprecation-header-00 который должен быть использован вместо. Я редактирую пост. BenC
Дата предупреждения в конце значения предупреждения здесь не имеет смысла, и онаЛучше пропустить это, либо вы рискуете запутать клиентов: «Если получатель. , , получает дату предупреждения, которая отличается отDate значение в том же сообщении, получатель ДОЛЖЕН исключить значение предупреждения. , , до . , , используя сообщение. ” Vasiliy Faronov
28

Вы могли бы использовать410 (ушел).

Вот'как W3CОпределения кода состояния Опишите это:

410 (ушел)

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

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

Проблема с 410 в том, что он не соответствуетчтобы быть устаревшим» требование ... Он прекрасно работает, когда API нет, но не то, чтобы этобудут уйти вбудущее. Julien Genestoux
Если вы вернете 410, вы нарушите свою обратную совместимость BenC
Это может быть следующим этапом устаревшего API Shiplu Mokaddim
410 Gone Это'не об устаревании, этомного о методе, доступном больше нет. Как сказал @BenC, лучше использоватьЗаголовок предупреждения sempasha

Похожие вопросы