【入門編】ヘッダー版APIバージョン管理(Acceptヘッダー)の仕様と実装 – Web APIアーキテクチャ・データ連携実践ガイド

APIの「バージョン」をどう伝える？：Acceptヘッダーで実現するスマートなAPI設計術

こんにちは。ネットワークの深淵を愛するインフラエンジニアです。

皆さんは、レストランで「いつものやつ」と注文したことはありますか？もし店員さんが「いつもの」が何を指すのか完璧に理解してくれていたら、注文はとってもスムーズですよね。

Web APIの世界でも、これと全く同じことが起きています。今日は、APIのバージョン管理の中でも、特にプロフェッショナルな現場で好まれる「メディアタイプ（Acceptヘッダー）によるバージョン管理」について、郵便配達の仕組みに例えながら紐解いていきましょう。

—

なぜAPIに「バージョン」が必要なの？

APIは、サーバー（お店）とクライアント（お客さん）の「約束事」です。でも、サービスが成長すれば「もっと新しい機能を追加したい！」「データの形式を少し変えたい！」という時が必ず来ます。

ここで問題になるのが、「古い約束のまま動いているアプリ」と「新しい約束を期待しているアプリ」の両方を、同時にどうやってさばくか、という点です。これを解決するのが「バージョン管理」です。

—

郵便配達で例える「メディアタイプ」という指定

APIのURLに /v1/users や /v2/users と書く方式は、住所そのものを変えてしまうようなものです。これに対し、今回紹介する Accept ヘッダーを使う方式は、「封筒のラベル（中身の指定）」を変えるイメージです。

郵便配達の例え

住所（URL）: https://api.myapp.com/users（ここまでは共通）
中身の指定（Acceptヘッダー）:
application/vnd.myapp.v1+json（「バージョン1の形式で送って！」というラベル）
application/vnd.myapp.v2+json（「最新のバージョン2で送って！」というラベル）

サーバーは、このラベルを見て「なるほど、このお客さんは古い形式を求めているな。じゃあ古い倉庫からデータを持ってこよう」と判断します。住所を変えずに、中身の形式だけでバージョンを制御できる。これが、REST APIの設計において「美しい」と言われる理由です。

—

なぜこの方式が「プロ好み」なのか？

1. URLが汚れない: リソース（ユーザー情報など）を指し示すURLが、バージョン番号でガチャガチャ汚染されません。
2. 純粋なリソース指向: RESTの原則では、URLはあくまで「モノの場所」であるべきです。バージョンはあくまで「表現形式」の違いなので、ヘッダーで指定するのが最も理にかなっているのです。

—

実装してみよう：コードで見る Accept ヘッダー

では、実際にAPIを叩くとき、どのようにヘッダーを指定するのか見てみましょう。Pythonの requests ライブラリを使った例です。

import requests

# サーバーに「バージョン1のJSON形式をください」と伝えます
url = "https://api.myapp.com/users"
headers = {
    "Accept": "application/vnd.myapp.v1+json"
}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    print("データを受け取りました！")
    print(response.json())

このように、ヘッダーに特定の文字列を忍ばせるだけで、サーバー側のロジックが「あ、これはv1のリクエストだな」と自動的に振り分けてくれるのです。

—

ブラウザのテストツールで試すには？

「でも、ブラウザのURLバーに直接打ち込めないじゃん！」と思いますよね。その通りです。ブラウザは基本的に「どんな形式でもいいからちょうだい！」というリクエストを送るのがデフォルトだからです。

そんな時は、「Postman」や「Insomnia」といったAPI開発専用のツールを使いましょう。

1. ツールを開いて GET メソッドを選択。
2. Headers（ヘッダー）タブを開く。
3. Key に Accept、Value に application/vnd.myapp.v1+json を入力。
4. 送信ボタンを押す！

これだけで、ブラウザ経由では体験できない「ヘッダーによるバージョンの出し分け」を自由自在にテストできます。

—

最後に：一歩ずつ理解していきましょう

最初から全てを理解しようとすると、ネットワークの専門用語に飲み込まれてしまいます。まずはこう考えてみてください。

「URLは場所、ヘッダーは注文書」。

サーバーという名のレストランで、どんな料理を、どのバージョンのレシピで提供してほしいか。それを伝えるための「丁寧な注文書」が Accept ヘッダーなんだ、と理解できれば、皆さんはもうAPI設計の第一歩を完璧に踏み出せています。

現場のインフラ環境では、このヘッダー情報を使って「どのサーバーにリクエストを振り分けるか」を制御することもあります。通信の裏側には、こうした細やかな気遣いが詰まっているんですよ。

それでは、また次回の深淵でお会いしましょう！