Конвенція щодо заголовка відповіді HTTP для сповіщення клієнтів про застарілий API

84

Я оновлюю наші кінцеві точки REST API, і я хочу повідомляти клієнтів, коли вони викликають кінцеву точку, що не підтримується.
Який заголовок я повинен використати у відповіді із повідомленням у формі "Ця версія API застаріла, будь ласка, ознайомтесь із останньою документацією, щоб оновити ваші кінцеві точки"

rest  http  http-status-codes  deprecation-warning 
— BlazingFrog
джерело

Відповіді:

72

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

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, заголовок Warning знаходиться в главі, що стосується кешування в документації. Однак 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) це попереджувальне повідомлення завжди буде дійсним у майбутньому. Отже, якщо відповідь (із попереджувальним повідомленням) надсилається кешем у проксі-сервері і дата повідомлення інша, попередження буде проігноровано, тоді як воно все ще буде дійсним.
— Редагую
Хіба це не "попереджувальний" заголовок пов'язаний з кешуванням? Я маю на увазі у своєму посиланні на документацію згадування про кешування, але також і те, що весь документ RFC, схоже, пов’язаний із кешуванням. Але Warningзаголовок справді виглядає як місце у вільному тексті для опису знецінення. Ці Deprecationта Sunsetзаголовки , зазначені в інших відповідях, здавалося б, витікаючи стандартним рішенням для опису старіння в тугіше потенційно більш машиночитаемом способом.
— Гаррі Вуд,
1
Warningheader не стосується лише кеш-пам’яті. Перше речення в Warningрозділі "Попередження можна використовувати для інших цілей, як кеш-пам’яті, так і інших".
— Челебі Мурат
37

Ви можете використовувати 410 (Gone) .

Ось як це описують Визначення коду стану W3C :

410 (зник)

Запитаний ресурс більше не доступний на сервері, і невідома адреса переадресації. Очікується, що цей стан вважатиметься постійним. Клієнти з можливостями редагування посилань ПОВИННІ видалити посилання на Request-URI після затвердження користувачем. Якщо сервер не знає або не має можливості визначити, чи є умова постійною, натомість слід використовувати код стану 404 (Не знайдено). Цю відповідь можна кешувати, якщо не вказано інше.

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

— Емануїл Русєв
джерело
36
Проблема 410 полягає в тому, що він не відповідає вимозі "застаріти" ... Він прекрасно працює, коли API відпадає, але не в тому, що його не буде в майбутньому .
— Julien Genestoux
3
Якщо ви повернете 410, ви порушите свою зворотну сумісність
— BenC
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 пропало!
— Harry Wood
4

Уточнення відповіді @ dret. Існує два відповідні заголовки HTTP для припинення дії: Deprecation( https://tools.ietf.org/html/draft-dalal-deprecation-header-00 ) та Sunset.

Для інформування користувачів про заплановане припинення Deprecationвикористання слід використовувати заголовок HTTP. Це вказує на те, що кінцева точка буде втрачена деякий час у майбутньому. Це також дозволяє вказати дату, коли це було оголошено, та описати альтернативні ресурси.

Щоб повідомити користувачів про заплановану дату припинення дії застарілого ресурсу, Sunsetслід використовувати заголовок на додаток до заголовка "Застаріття". Це описано в розділі №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 .

— sdatspun2
джерело
3

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

— дрет
джерело
Використовуючи наш веб-сайт, ви визнаєте, що прочитали та зрозуміли наші Політику щодо файлів cookie та Політику конфіденційності.
Licensed under cc by-sa 3.0 with attribution required.