こんにちは、インフラアーキテクトの私です。
Web APIの設計や運用に携わるエンジニアなら、一度はこんな悪夢にうなされたことがあるはずです。「ある日突然、社内システムや外部連携先のモバイルアプリが古いAPIを叩き続け、サーバー側の改修で盛大にエラーを吐き始めた」という修羅場です。
「バージョンを変えるって言ったよね？」「聞いてないよ！」という開発者間の不毛な押し問答。これを防ぐために、URLに /v1/ と入れるだけのバージョン管理に頼っていませんか？
今回は、RFC 8594で標準化された Sunset ヘッダーと、IETFのドラフト（そして実業界のデファクトスタンダード）である Deprecation ヘッダーを用いた、スマートかつ強制力のあるAPI廃止通知の仕組みを徹底解説します。パケットの往来とプロトコルの美しさに酔いしれながら、現場で即座に使える実践知を伝授しましょう。
—
なぜURLのバージョン管理だけでは破綻するのか
多くのWeb APIは、 /api/v1/users のようにパスにバージョンを含めることで、互換性の破壊に備えています。これは基本のキですが、これだけでは「クライアントにいつまでに移行してほしいか」という時間軸の概念が完全に欠落しています。
サーバー側としては「v1は半年後に止めます」と思っていても、それを伝える手段がドキュメント（誰も読まない）やメール（誰も見ない）しかなければ、クライアント開発者は動きません。結果として、廃止期限の当日になってパニックが起きるわけです。
ここで登場するのが、HTTPのレスポンスヘッダーによる機械可読な（Machine-readable）移行勧告です。プロトコル自身に「このAPIはもうすぐ死にますよ」と語らせることで、クライアント側のログ監視や自動テストにフックさせることが可能になります。
—
2つの主役：Deprecation と Sunset の仕様と役割
APIのライフサイクル管理において、私たちが覚えておくべきHTTPヘッダーは主に2つあります。それぞれの役割とRFCの定義を見ていきましょう。
1. Deprecation ヘッダー（非推奨の宣言）
- 役割: このエンドポイント、あるいはこのリソースが「非推奨（Deprecated）」になったことを伝えます。
- 仕様の背景: これは現在、IETFで標準化が進められているドラフト仕様（
draft-ietf-httpapi-deprecationheader）に基づきます。 - 値のフォーマット: 通常はHTTP日付（IMF-fixdate）または真偽値（
true）が入りますが、実務では「いつから非推奨なのか」を明確にするためにHTTP日付を入れるのが美しいとされています。 - 例:
Deprecation: @1717113600（Unixタイムスタンプ） またはDeprecation: Sat, 01 Jun 2024 00:00:00 GMT
2. Sunset ヘッダー（廃止・日没の宣告）
- 役割: このリソースが完全に削除され、アクセスできなくなる日時（日没＝Sunset）を指定します。
- 仕様の背景: こちらは RFC 8594 として正式に標準化されています。
- 値のフォーマット: HTTP-date形式で厳密に記述します。
- 例:
Sunset: Wed, 31 Dec 2024 23:59:59 GMT
この2つを組み合わせることで、「このAPIは2024年6月に非推奨となり（Deprecation）、2024年末には完全になくなります（Sunset）」というライフサイクルを、クライアントのプログラムに対して正確に伝えることができるのです。
—
通信フロー：プロトコルが伝える「終わりの始まり」
実際にクライアントが古いAPI（/v1/items）にリクエストを投げた際、プロトコル上で何が起きているのか、シーケンスを見てみましょう。
Client (Mobile/SPA/Microservice) Server / API Gateway
│ │
│── GET /v1/items ─────────────────────────────▶│
│ │
│ (HTTP/1.1 200 OK) │
│ Deprecation: Sat, 01 Jun 2024 00:00:00 GMT │
│ Sunset: Wed, 31 Dec 2024 23:59:59 GMT │
│ Link: </v2/items>; rel="successor-version" │
│◀── [JSON Body: Data] ─────────────────────────│
│ │
│ ※クライアントのログ基盤がヘッダーを検知し、 │
│ 開発チームにアラートを飛ばす。 │ここで注目してほしいのが、Link ヘッダーの活用です。RFC 8288で定義される Link ヘッダーを併用し、rel="successor-version" を指定して「後継のAPIはこちらですよ（/v2/items）」と指し示すことで、クライアントの移行作業を劇的にスムーズにできます。これぞプロトコルの美しさです。
—
実装と設定の実例
では、現場のインフラやコードでこれをどう実装するか、具体的なサンプルを見ていきましょう。
1. Nginx / API Gatewayでのリバースプロキシ設定
アプリケーションコードを改修する余裕がない場合や、レガシーなバックエンドの前に立つAPI Gateway（Nginx等）で一括してヘッダーを付与する場合の設定例です。
server {
listen 80;
server_name api.example.com;
location /v1/ {
# 古いv1エンドポイントへのアクセスすべてに非推奨・廃止ヘッダーを挿入
add_header Deprecation "Sat, 01 Jun 2024 00:00:00 GMT" always;
add_header Sunset "Wed, 31 Dec 2024 23:59:59 GMT" always;
add_header Link "</v2/>; rel=\"successor-version\"" always;
# バックエンドのアップストリームへ転送
proxy_pass http://backend_v1_cluster;
}
}*実務Tips:* always パラメーターを忘れると、ステータスコードが 4xx や 5xx の場合にヘッダーがドロップされてしまうことがあるため、必ず付与するようにしましょう。
2. Python (FastAPI) によるアプリケーション層での実装
モダンなWebフレームワークであれば、カスタムミドルウェアやレスポンスヘッダーの操作で容易に実装できます。
from datetime import datetime, timezone
from fastapi import FastAPI, Response
app = FastAPI()
@app.get("/v1/users")
async def get_legacy_users(response: Response):
# Deprecationヘッダー（非推奨化された日時）
response.headers["Deprecation"] = "Sat, 01 Jun 2024 00:00:00 GMT"
# Sunsetヘッダー（完全廃止日時）
response.headers["Sunset"] = "Wed, 31 Dec 2024 23:59:59 GMT"
# 後継バージョンへのリンク
response.headers["Link"] = '</v2/users>; rel="successor-version"'
return [{"id": 1, "name": "Legacy User"}]3. クライアント側（JavaScript / Fetch API）での検知コード
フロントエンドやBFF（Backend for Frontend）層で、これらのヘッダーを監視・検知し、Sentryなどのエラー監視ツールやログに飛ばす仕組みの例です。
async function fetchLegacyApi(url) {
const response = await fetch(url);
// Deprecation ヘッダーの存在チェック
const deprecationDate = response.headers.get('Deprecation');
const sunsetDate = response.headers.get('Sunset');
const successorLink = response.headers.get('Link');
if (deprecationDate) {
console.warn(`[API WARN] このエンドポイントは非推奨です (${url})。`);
console.warn(`廃止予定日 (Sunset): ${sunsetDate}`);
// 必要に応じてモニタリングツールへ送信
// Sentry.captureMessage(`Deprecated API used: ${url}`, 'warning');
}
return response.json();
}—
現場でハマる罠とトラブルシューティング
最後に、私が実際の現場で遭遇した、この手の子気味良い仕組みを導入する際の「落とし穴」をいくつか共有しておきます。
1. タイムゾーンの罠
SunsetやDeprecationの日付は、必ず UTC（GMT） で記述してください。ローカルタイムやJST（+09:00）で記述すると、クライアント側の解釈が割れ、予期せぬタイミングでアクセスが遮断される原因になります。
2. CDNやリバースプロキシのキャッシュ
- APIのレスポンスがCDN（CloudflareやCloudFrontなど）でキャッシュされている場合、古いレスポンス（ヘッダーがない状態）がキャッシュされ続けてしまい、クライアントに通知が届かない現象が起きます。廃止ヘッダーを入れる際は、該当パスのキャッシュポリシー（
Cache-Control）をno-cacheにするか、CDN側でヘッダーが正しくバリエーションとして認識されるよう設定を確認してください。
3. クライアントの無視
- ヘッダーを入れただけでは、人間（開発者）は動きません。最初のうちはログ警告だけに留め、Sunsetの期日が近づいたら、段階的にステータスコードを
410 Goneや400 Bad Requestに切り替える「強制終了シナリオ」をチームであらかじめ合意しておくことがプロジェクト成功の鍵となります。
—
まとめ
APIのバージョン管理は、単にコードを書き換える技術的な作業ではなく、サービスを利用する開発者コミュニティや他チームとの「コミュニケーションの契約」です。
URLの変更だけに頼るのではなく、Deprecation と Sunset ヘッダーを正しく響かせることで、あなたの構築したAPIは、単なる「動くプログラム」から、インフラとしての信頼性を備えた「美しいシステム」へと昇華します。
さあ、今日のデプロイから、古いエンドポイントに「終わりの日」を優しく、そして厳格に告げてやりましょう。
コメント