URLリソースの非推奨を示すDeprecationヘッダ

APIのURLや、リソースが非推奨となっている事を示す、新しいDeprecationヘッダを定義する「The Deprecation HTTP Header Field」という仕様が提出されています。

この仕様はすでに、HTTPAPI WGに採用せています。なお、HTTPAPI WGは2020年10月 新しく出来たWGで、HTTPのAPI利用のための拡張を議論するWGになっています。

Deprecationヘッダ

レスポンスに、下記の様なヘッダを付けることで、そのリソースが非推奨になっている事を示します

Deprecation: true
Deprecation: Sun, 11 Nov 2018 23:59:59 GMT
  • true: 非推奨になっている
  • 日付: 指定した日付で非推奨になる

Linkヘッダ

RFC8288 Web Linking」の仕組みを用いて、 Linkヘッダで追加の情報を与えます

relにdeprecationを指定することで、非推奨に関するドキュメントのリンクを提供できます

   Link: <https://developer.example.com/deprecation>;
         rel="deprecation"; type="text/html"

relにalternateを指定することで、代替エンドポイントを提供できます

   Deprecation: Sun, 11 Nov 2018 23:59:59 GMT
   Link: <https://api.example.com/v1/clients>; rel="alternate"

relにsuccessor-versionを指定することで、次のバージョンエンドポイントを指定します。

  Deprecation: Sun, 11 Nov 2018 23:59:59 GMT
  Sunset: Wed, 11 Nov 2020 23:59:59 GMT
  Link: <https://api.example.com/v2/customers>; rel="successor-version",
        <https://developer.example.com/deprecation>; rel="deprecation"

合わせてsunsetヘッダで廃止時間も示せますね
asnokaze.hatenablog.com