web-dev-qa-db-ja.com

非推奨APIをクライアントに通知するHTTP応答ヘッダーの規則

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

resthttphttp-status-codesdeprecation-warning
70
BlazingFrog

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

Warning: 299 - "Deprecated API"

また、警告を発する「エージェント」で「-」を指定し、warn-textでより明確にすることもできます。

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は、警告コード199 The warning text can include arbitrary information to be presented to a human user or logged.

このドラフト https://tools.ietf.org/html/draft-dalal-deprecation-header- は、適切な代替となる新しいヘッダー「Deprecation」を提案しています。

63
BenC

410（Gone） を使用できます。

W3Cの ステータスコード定義 の説明は次のとおりです。

410（なくなった）

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

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

33
Emanuil Rusev

1 （永続的に移動）を使用したか、または行ったはずです。300シリーズのコードは、クライアントに実行するアクションがあることを伝えることになっています。

13
u07ch

207 Multi-Status response。成功した応答であることを示しますが、潜在的に2番目の非推奨ステータスもあります。

5
typeoneerror

@dretの応答を改良します。非推奨に関連する2つのHTTPヘッダーがあります：Deprecation（ https://tools.ietf.org/html/draft-dalal-deprecation-header- ）およびSunset。

廃止予定についてユーザーに通知するには、Deprecation HTTPヘッダーを使用する必要があります。これは、将来エンドポイントがドロップされることを示しています。また、これが発表された日付を示したり、代替リソースを説明したりすることもできます。

廃止予定のリソースの日没予定日をユーザーに通知するには、Deprecationヘッダーに加えてSunsetヘッダーを使用する必要があります。これは、セクション＃5 https://tools.ietf.org/html/draft-dalal-deprecation-header-00#section-5 で説明されています。

ドラフト＃11 https://tools.ietf.org/html/draft-wilde-sunset-header-11Sunsetヘッダーの=セクション1.4でもこの側面を明確にします- https://tools.ietf.org/html/draft-wilde-sunset-header-11#section-1.4 .

2
sdatspun2

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

2
dret