要約

  • 2025年3月のRFC 9745は、Structured Fieldsの日付を含むDeprecation応答フィールドを定義した。廃止予定の扱いが始まっても、資源は従来どおり動作し得る。
  • deprecationというLink関係は移行方針の文書を示せる。日付が付く前から使える。2019年のRFC 8594が定めたSunsetは、応答しなくなると見込む別の日付だ。
  • 印がまず指すのは、その応答で識別された資源である。API全体へ広げるには提供者が範囲の規則を示す必要がある。

成功した応答に付いた退場札

APIの引退は、最後の障害から始まるとは限らない。要求は成功し、監視画面も正常を示す。その裏で提供者は新しい利用者を別のインターフェースへ導き、既存の顧客には移行を準備してほしいと考える。通知が人向けの文書にだけあれば、実際の通信を見ている開発者には届きにくい。要求が失敗して初めて分かるのであれば、移行と試験に使える時間は消えている。

RFC 9745は、退場の知らせをHTTP応答に載せた。Deprecationはその応答が識別する資源に関する日付を伝える。値はStructured FieldsのDate項目で、仕様の例はDeprecation: @1688169599と書く。これは2023年6月30日23時59分59秒UTCに当たる。未来の日付ならその時点で廃止予定の扱いに入り、過去ならすでに入っていることを示す。

注目すべきは、印が付いても資源の動作は変わらないという規定だ。同じパケットが正常な結果と将来への警告を運べる。顧客は今日の成功を確認しながら、新しい依存関係を作るべきか判断する。提供者の一行の通知が、別の会社の開発計画を動かす。

範囲は応答ごとに確かめる。標準の基本対象は、その応答の資源である。提供者がAPI全体や複数の経路に同じ予定を適用したければ、その広がりをAPIの規則として説明する。一つのヘッダーを見ただけで全経路の終わりを推測すれば、運営者の計画を読み違える。

説明書だけ先に届くこともある

同じRFCはLinkの関係型deprecationも登録した。リンク先には移行先、方針、予定などの説明を置ける。日付フィールドより先にリンクを送ることもできる。つまり、提供者はまだ資源を廃止予定として扱っていない段階で、将来どのように告知するかを公開できる。

日付だけではクライアントの移行は進まない。新しいAPIの応答形式、権限、データの移し方を調べ、試験し、製品を出し直す必要がある。稼働中の応答から文書へたどれることには価値がある。ただし文書の具体性と代替手段の使いやすさは提供者が決める。共通のリンク形式は説明を見つけやすくし、移行作業は顧客の机に残る。

廃止予定の日と止まる日

2019年5月のRFC 8594はSunsetを定めた。資源が応答しなくなると見込む時刻を、HTTPの日付形式で示す。Deprecationが扱うのは、まだ動いている資源を今後の依存先として勧めない時点だ。前者は利用を続ける判断、後者は可用性の終わりを意識させる。時間の性質が違う。

RFC 9745は両方を併用できるとし、Sunsetの日付をDeprecationより前に置くことを禁じた。例では2023年6月30日に廃止予定となり、2024年6月30日に応答しなくなる見込みを示す。逆なら、使わないようにと告げる前に閉じるという矛盾した予定になる。書式にも差があり、Deprecationは@付きの構造化日付、Sunsetは古いHTTP日付を使う。

実際にどのサービスが採用したかを知るには、日時が残る応答記録が要る。RFCが確立したのは、稼働中の資源自身が利用者に移行を促せる仕組みだ。時計の針は提供者が置き、顧客はその針に合わせてリリースを組む。