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
