[解決済み] 非推奨APIをクライアントに通知するためのHTTPレスポンスヘッダに関する規約

質問

REST API のエンドポイントをアップグレードしているのですが、廃止予定のエンドポイントを呼び出しているときに、クライアントに通知したいのです。

この API のバージョンは非推奨です。最新のドキュメントを参照して、エンドポイントを更新してください。

どのように解決するのですか？

後方互換性を保つために、ステータスコードは何も変更しません。私なら、レスポンスに "Warning" ヘッダーを追加します。

Warning: 299 - "Deprecated API"

警告を発する "Agent" で "-" を指定し、警告文の中でより明示的にすることもできます。

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 . Warn-code 299は一般的なもので、"Deprecated"は標準的なものではありません。

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

今まで使ったことはないのですが、今後Rest APIが成熟してきたら組み込んでみようと思っています。

編集しました（2019-04-25）。ハリー・ウッド氏（@Harry Wood）が言及しているように、Warningヘッダはドキュメントのキャッシュに関連する章に記載されています。しかし、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 はこのように言っています。 ヘッダは非推奨とされています。