REST APIエンドポイントをアップグレードしており、非推奨になるエンドポイントを呼び出しているときにクライアントに通知したいと思います。
「このAPIバージョンは非推奨です。最新のドキュメントを参照してエンドポイントを更新してください」というメッセージとともに、応答でどのヘッダーを使用する必要がありますか
REST APIエンドポイントをアップグレードしており、非推奨になるエンドポイントを呼び出しているときにクライアントに通知したいと思います。
「このAPIバージョンは非推奨です。最新のドキュメントを参照してエンドポイントを更新してください」というメッセージとともに、応答でどのヘッダーを使用する必要がありますか
回答:
下位互換性を保つために、ステータスコードの内容は変更しません。応答に「警告」ヘッダーを追加します：
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は一般的であり、「非推奨」は標準ではありません。
HTTP警告をログに記録して監視するようにAPIクライアントに指示する必要があります。
今まで使ったことがありませんが、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で新しいヘッダー「Deprecation」を提案しています。
Dateヘッダーと同じ方法でフォーマットする必要があります"Thu, 02 Apr 2015 12:25:32 GMT"。
Warningヘッダーは非推奨を説明するためのフリーテキストの場所として見栄えがします。DeprecationそしてSunset他の回答で述べたヘッダは、タイトより潜在的に機械可読な方法で廃止を記述するための新たな標準ソリューションであるように思われます。
Warningヘッダーはキャッシュのみに関連していません。このWarningセクションの最初の文は、「警告は、キャッシュ関連とそれ以外の両方の目的で使用できます」です。
410（Gone）を使用できます。
W3Cのステータスコード定義は次のように説明しています。
410（なくなった）
要求されたリソースはサーバーで使用できなくなり、転送アドレスは不明です。この状態は永続的であると見なされると予想されます。リンク編集機能を備えたクライアントは、ユーザーの承認後にRequest-URIへの参照を削除する必要があります。サーバーが状態が永続的であるかどうかを認識していないか、判断する機能がない場合は、代わりにステータスコード404（見つかりません）を使用する必要があります。この応答は、特に明記されていない限り、キャッシュ可能です。
410応答は、主に、リソースが意図的に使用不可であり、サーバー所有者がそのリソースへのリモートリンクを削除することを望んでいることを受信者に通知することにより、Webメンテナンスのタスクを支援することを目的としています。このようなイベントは、期間限定のプロモーションサービスや、サーバーのサイトで作業しなくなった個人に属するリソースでよく見られます。永続的に利用できないすべてのリソースを「なくなった」とマークしたり、マークを長期間保持したりする必要はありません。これは、サーバー所有者の裁量に任されています。
410 Goneそれは非推奨についてではなく、もはや利用できない方法についてです。@BenCが言ったように、より良い方法は警告ヘッダー
私は301（永久に移動）を使用していました。300シリーズのコードは、クライアントに実行するアクションがあることを通知することになっています。
207 Multi-Status応答が成功したことを示す応答をお勧めしますが、2番目の非推奨ステータスになる可能性もあります。
Deprecationヘッダー（クライアントは残念ながら無視する可能性があります）から始めて、後でこの207コードを使用し、後で301を移動し、最後に410を削除します。
@dretの応答を調整します。非推奨に関連する2つのHTTPヘッダーがあります：Deprecation（https://tools.ietf.org/html/draft-dalal-deprecation-header-00）とSunset。
計画されている非推奨についてユーザーに通知するには、DeprecationHTTPヘッダーを使用する必要があります。これは、エンドポイントがドロップされることを示しているいくつかの時間を未来に。また、これが発表された日付を示したり、代替リソースを説明したりすることもできます。
非推奨のリソースの廃止予定日をユーザーに通知するには、非Sunset推奨ヘッダーに加えてヘッダーを使用する必要があります。これについては、セクション5https：//tools.ietf.org/html/draft-dalal-deprecation-header-00#section-5で説明されています。
ヘッダーのドラフト＃11 https://tools.ietf.org/html/draft-wilde-sunset-header-11は、Sunsetセクション1.4https ：//tools.ietf.org/html/draft-wildeでもこの側面を明確にしています。 -sunset-header-11＃section-1.4。
Sunsetリソースの今後の非推奨を通知することを目的とした、呼ばれるHTTPヘッダーフィールドがあります。https://tools.ietf.org/html/draft-wilde-sunset-headerは、RFCになる最終段階にあります。理想的には、APIは、使用することを文書化してSunset、クライアントが必要に応じてAPIを探し、それに基づいて行動できるようにする必要があります。
Date同じメッセージの値とは異なる警告日を受信した場合、受信者は警告値を除外する必要があります。。。前 。。。メッセージを使用します。」