97

REST API エンドポイントをアップグレードしていて、非推奨のエンドポイントを呼び出しているときにクライアントに通知したいと考えています。
「この API バージョンは非推奨です。エンドポイントを更新するには、最新のドキュメントを参照してください」という行に沿ったメッセージを含む応答で、どのヘッダーを使用する必要がありますか?

4

6 に答える 6

79

下位互換性を維持するためにステータス コードを変更することはありません。応答に「警告」ヘッダーを追加します。

Warning: 299 - "Deprecated API"

また、警告を発する「Agent」で「-」を指定し、warn-text でより明示的にすることもできます。

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

警告ヘッダーは、https ://www.rfc-editor.org/rfc/rfc7234#section-5.5 で指定されています。警告コード 299 は一般的なもので、「非推奨」は標準ではありません。

HTTP 警告をログに記録して監視するように API クライアントに指示する必要があります。

今まで使ったことはありませんでしたが、会社がRest APIでより成熟したら、統合します。

編集 (2019-04-25): @Harry Wood が言及したように、警告ヘッダーはドキュメントのキャッシュに関連する章にあります。ただし、RFCは明確ですWarnings can be used for other purposes, both cache-related and otherwise.

別の方法を希望する場合は、このドラフトhttps://datatracker.ietf.org/doc/html/draft-dalal-deprecation-header-00で新しいヘッダー「Deprecation」を提案しています。

編集 (2021-01-04) : @Dima Parzhitsky が言及したように、MDN はこのヘッダーは非推奨であると言います

于 2015-04-14T09:29:16.470 に答える
42

410 (Gone)を使用できます。

W3C のステータス コード定義では、次のように説明されています。

410 (なくなった)

要求されたリソースはサーバーで使用できなくなり、転送先アドレスも不明です。この状態は永続的であると考えられています。リンク編集機能を持つクライアントは、ユーザーの承認後に Request-URI への参照を削除する必要があります。状態が永続的かどうかをサーバーが認識していない場合、または判断する機能がない場合は、代わりにステータス コード 404 (Not Found) を使用する必要があります。特に明記しない限り、この応答はキャッシュ可能です。

410 応答は、主に、リソースが意図的に利用できないこと、およびサーバーの所有者がそのリソースへのリモート リンクを削除することを望んでいることを受信者に通知することにより、Web メンテナンスのタスクを支援することを目的としています。このようなイベントは、期間限定の販売促進サービスや、サーバーのサイトでもはや働いていない個人に属するリソースによく見られます。永久に利用できないすべてのリソースを「なくなった」とマークしたり、マークを一定期間保持したりする必要はありません。これはサーバー所有者の裁量に任されています。

于 2013-03-01T15:17:24.687 に答える
16

私は301 (Moved Permanently) を使っていた/行っていた 300 シリーズのコードは、クライアントに実行するアクションがあることを伝えることになっています。

于 2012-12-14T18:20:47.547 に答える
5

Sunsetリソースの今後の非推奨を通知することを目的とした、呼び出される HTTP ヘッダー フィールドがあります。https://datatracker.ietf.org/doc/html/draft-wilde-sunset-headerは、RFC になる最終段階にあります。理想的には、API は を使用することを文書化してSunset、必要に応じてクライアントがそれを探してそれに基づいて行動できるようにする必要があります。

于 2019-01-15T00:20:58.783 に答える