こんにちは！ネットワークの深淵と、そこで息づくプロトコルのドラマを愛するインフラアーキテクトです。
Webアプリケーションを作ったり、スマートフォンアプリと通信したりするときに欠かせない「Web API」。皆さんも日々の開発で、URLを叩いてJSONデータを受け取る仕組みをたくさん作っていることと思います。
ところで、APIを運営していると、こんな悩みに直面したことはありませんか？
「機能を追加したいけれど、今のAPIの形だと古いアプリが壊れてしまう……」
「いつまでも古いバージョンのAPIを放置するわけにはいかないけれど、いきなり止めたらユーザーから大クレームが来てしまう……」
今回は、そんなAPIの「世代交代」を平和的かつスマートに進めるための、とっても重要な仕組みについてお話しします。難しそうな英語のヘッダーが出てきますが、身近な例えを交えて一歩ずつ理解していきましょう！
—
1. 郵便配達と「宛先変更」の物語でイメージするAPIの寿命
突然ですが、あなたが長年住み慣れたお家から、新しい街へお引越しをすることになったと想像してみてください。
お友達や大切な取引先に新しい住所を伝えるわけですが、うっかり連絡し忘れた人や、古い住所のまま手紙を出してしまう人もいるかもしれませんよね。そんなとき、郵便局はどうするでしょうか？
しばらくの間は、古い宛先の郵便物に「この住所はもう使われていませんよ。新しい住所はこちらです」という可愛いスタンプ（付箋）を押して、新しい新居へ転送してくれたりしますよね。そして、一定期間が過ぎたら、いよいよその古い宛先への配達は完全に終了します。
Web APIの世界も、これとまったく同じなんです。
APIをバージョンアップ（例えば v1 から v2 へ）するとき、古い v1 を使っているクライアント（スマホアプリや他のシステムのプログラム）に対して、「このAPIはもうすぐ使えなくなるから、早くお引越し（移行）してね！」と優しく、かつ正確に伝える必要があります。
そのために使われるのが、今回主役となる2つのHTTPヘッダー、Deprecation と Sunset です。
—
2. Deprecation と Sunset ってどんなヘッダー？
HTTPヘッダーとは、Webサーバーとブラウザ（またはアプリ）がやり取りする「荷物の送り状」のようなものです。ここにちょっとしたメモ書きを添えることで、クライアントに大切なメッセージを伝えることができます。
一歩ずつ、それぞれの役割を見ていきましょう！
Deprecation ヘッダー（「このAPI、もう古くなっていますよ」のサイン）
- 意味: 「非推奨（サヨナラ準備中）」を表します。
- 役割: このヘッダーが付いて返ってきたら、「このAPIは将来的に廃止されることが決まったので、新しいバージョンへの切り替えを検討してくださいね」という開発者への警告になります。
Sunset ヘッダー（「この日にお店を閉めます（日没）」のタイムリミット）
- 意味: 「廃止日時（サンセット・日没）」を表します。
- 役割: 「このAPIは、〇年〇月〇日の〇時〇分に完全に停止（日没）しますよ」という具体的な締め切り日時をカレンダーのようにはっきりと示します。
この2つが揃うことで、クライアント側は「いつまでに、何をすればいいのか」を正確に把握できるようになるわけですね。
—
3. 実際のHTTPレスポンスを見てみよう
それでは、実際にサーバーがクライアントへ返すレスポンスの様子を覗いてみましょう。裏側でどんなやり取りが行われているのか、具体的なコード例で見てみます。
APIサーバーから返されるHTTPレスポンスのヘッダー部分は、次のようなイメージになります。
HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: @1735689600
Sunset: Wed, 31 Dec 2025 23:59:59 GMT
Link: <https://api.example.com/v2/users>; rel="successor-version"
{
"message": "このAPIバージョンは非推奨です。v2への移行をお願いします。"
}なんだか見慣れない文字が並んでいますね。でも大丈夫、一つずつ分解して意味を確認していきましょう！
Deprecation: @1735689600:
これは「UNIXタイムスタンプ」という形式で、非推奨になった（または通知された）日時を表しています。この数字を日時に直すと「2025年1月1日」になります。
Sunset: Wed, 31 Dec 2025 23:59:59 GMT:
こちらは人間にも読みやすいHTTP日付のフォーマットで、「2025年の大晦日の深夜にこのAPIは終了しますよ」という正確なタイムリミットを伝えています。
Link: <https://api.example.com/v2/users>; rel="successor-version":
「お引っ越し先はこちらの新しいURL（後継バージョン）ですよ」と親切に案内してくれるおまけのヘッダーです。これがあると、プログラムが自動で新しいURLを検知しやすくなります。
—
4. サーバー側（バックエンド）での実装アプローチ
「なるほど、概念は分かったけれど、実際にどうやってサーバーに組み込めばいいの？」という疑問が湧きますよね。
例えば、人気のプログラミング言語であるPythonの軽量Webフレームワーク「Flask」を使って、古いAPIのエンドポイントにこれらのヘッダーをサクッと付与するコードを見てみましょう。実務でもそのまま参考にしやすいように、日本語のコメントをたっぷり添えておきますね。
from datetime import datetime
from flask import Flask, jsonify, make_response
app = Flask(__name__)
@app.route('/v1/users', methods=['GET'])
def get_old_users():
"""
【古いバージョンのAPIエンドポイント（v1）】
ここにアクセスがあった場合、通常のデータを返しつつ、
非推奨と廃止予定日をHTTPヘッダーに含めて警告します。
"""
# 返却するダミーデータ
user_data = [{"id": 1, "name": "インフラ太郎"}]
# レスポンスオブジェクトを作成
response = make_response(jsonify(user_data))
# 1. Deprecationヘッダーの付与（非推奨になったことを伝える）
# 例として、2025年1月1日 00:00:00 UTC をUNIXタイムスタンプで指定
response.headers['Deprecation'] = '@1735689600'
# 2. Sunsetヘッダーの付与（完全停止する期限を伝える）
response.headers['Sunset'] = 'Wed, 31 Dec 2025 23:59:59 GMT'
# 3. Linkヘッダーで新しい移行先（後継バージョン）を明示する
response.headers['Link'] = '<https://api.example.com/v2/users>; rel="successor-version"'
# レスポンスをクライアントに返す
return response
if __name__ == '__main__':
app.run(port=5000)このように、サーバー側のコードでたった数行のヘッダーを追加するだけで、世界中のクライアント（を利用する開発者たち）に対して、穏便かつ明確に「お引越しの準備」を促すことができるのです。
—
5. まとめ：美しいAPI設計は「思いやり」から生まれる
今回は、APIのバージョン管理における非推奨通知である Deprecation および Sunset ヘッダーについて、郵便配達の例えを交えながら解説しました。
Deprecationヘッダー で「このAPIはもうすぐ古いものになりますよ」と早めに警告する。Sunsetヘッダー で「いつ完全に使えなくなるのか」の期限をクリアに示す。Linkヘッダー を添えて、新しい移行先へスマートに誘導する。
インフラやネットワークの世界、そしてAPIの設計において、最も大切なのは「システムを綺麗に保つこと」はもちろんですが、それを使っている「ヒト（開発者やユーザー）」に対する細やかな思いやりやコミュニケーションだったりします。
いきなりAPIを遮断してシステムを壊してしまうのではなく、こうした標準的なヘッダーを使って優しく移行を促せるエンジニアになれたら、とっても素敵ですよね。
皆さんの設計するAPIが、世界中のエンジニアに愛される美しく優しいものになりますように。それでは、また次回の技術の深淵でお会いしましょう！
コメント