【ITニュース解説】Code Smell 309 - Query Parameter API Versioning

システムエンジニアを目指す皆さんにとって、API（Application Programming Interface）は非常に重要な概念だ。APIは、異なるソフトウェア同士が互いに情報をやり取りするための約束事や窓口のようなものだ。例えば、スマートフォンのアプリが天気予報を取得したり、SNSに投稿したりする際に、裏側では提供されているAPIを通じてサーバーと通信している。このようなAPIは、一度公開されると多くの外部システムやアプリケーションに使われるため、安易に変更することはできない。

APIが広く使われるようになると、新しい機能を追加したり、既存の機能を改善したりする必要が出てくる。しかし、APIの変更が以前のバージョンと互換性がなくなってしまう（これを「破壊的変更」と呼ぶ）と、そのAPIを使っている既存のシステムが動かなくなってしまうだろう。例えば、APIが返すデータ形式が変わったり、必要な情報が変わったりすると、既存のアプリは新しい形式に対応できずエラーを起こしてしまう。この問題を避けるために、「APIバージョン管理」という手法が用いられる。これは、APIにバージョン番号を付けて管理することで、古いAPIを使い続けるクライアントと、新しいAPIを使いたいクライアントの両方に対応できるようにするものだ。

APIのバージョンを管理する方法はいくつかあるが、その一つに「クエリパラメータ」を使う方法がある。URLの末尾に?version=2のようにバージョン番号を付加する形式だ。しかし、この方法は「コードの悪臭（Code Smell）」、つまり、見た目や動作は問題なくとも、将来的に大きな問題を引き起こす可能性のある、望ましくない実装パターンとされている。なぜなら、クエリパラメータをバージョン管理に使うことは、多くの複雑さやメンテナンス上の課題を生み出すからだ。

まず、クエリパラメータは通常、APIに渡す追加情報や条件（例えば、?limit=10のように取得件数を指定するなど）に使われるものだ。ここにバージョン情報が混ざると、URLが煩雑になり、何のためのパラメータなのかが分かりにくくなる。これは「パラメータの混乱」や「URLの煩雑化」につながる。また、開発者が異なるAPIエンドポイントでバージョン管理の方法を統一しない「一貫性のないバージョン管理」を引き起こしやすく、結果的に「高いメンテナンスコスト」を招く。例えば、APIのバージョンが?v=1だったり?api-version=2だったりとバラバラだと、利用者はどのパラメータを使えば良いか混乱し、「クライアントエラー」につながる可能性も高まる。

特に問題となるのは、クエリパラメータがAPIの動作を決定する主要な要素であるかのように扱われる点だ。これはクエリパラメータの本来の「間違った意味論」であり、「隠れた複雑性」を生み出す。もし新しい機能を追加した際に、偶然バージョン指定用のパラメータと名前が衝突するようなことがあれば、「パラメータの衝突」が発生し、予期せぬ動作や「破壊的変更」につながることもある。このような状態では、古いクライアントが新しい変更に対応できず、「後方互換性の問題」が頻発する可能性がある。

では、どのようにAPIバージョンを管理するのが望ましいのだろうか。記事では主に二つの推奨される方法が示されている。一つは「URLパス」を使う方法、もう一つは「HTTPヘッダー」を使う方法だ。

「URLパス」を使う方法は最も一般的で分かりやすい手法だ。これは、https://example.com/api/v2/itemsのように、URLのパス部分にバージョン番号を埋め込むものだ。この方法の利点は、バージョンが一目で分かり、異なるバージョンのAPIがそれぞれ独立したリソースとして扱われるため、セマンティック（意味論）的にも自然であることだ。クライアントもアクセスしたいAPIのバージョンをURLから明確に判断できる。サンプルコードのhttps://eratostenes.com/api/v2/primes?limit=10のように、URLの中に/v2/とバージョンが明示されている。

もう一つの方法は、「HTTPヘッダー」を使うものだ。これは、APIリクエストのヘッダー情報（例えば、Accept: application/vnd.myapi.v2+jsonのように）にバージョン情報を含めるものだ。この方法の利点は、URLをシンプルに保てることだ。URL自体はhttps://example.com/api/itemsのようにバージョンを含まず、クライアントはヘッダーを通じて特定のバージョンのAPIを要求する。ただし、URLパスに比べてバージョン情報が視覚的に分かりにくく、開発者がデバッグする際に少し手間がかかるという側面もある。サンプルコードでは、Acceptヘッダーにv2という情報を含めることでバージョンを指定している。

記事のサンプルコードでは、PHPの例を使って「間違った」クエリパラメータ方式と、「正しい」URLパス方式、そして「HTTPヘッダー」方式の処理の違いが示されている。間違った例では、URLの?version=2を直接読み取ってif/else文で処理を分岐している。これは一見シンプルに見えるが、前述の通り多くの問題を含んでいる。一方、URLパスを使った例では、https://eratostenes.com/api/v2/primesのようにURLのパスに含まれる/v2/を正規表現で抽出し、そのバージョン番号に基づいて処理を分岐させている。また、HTTPヘッダーを使った例では、リクエストヘッダーからバージョン情報を抽出して処理を分岐している。これらの「正しい」方法は、バージョン管理の意図が明確で、拡張性やメンテナンス性に優れている。

APIバージョンは、常に上げるべきではない。記事では、「バージョン管理は破壊的変更があった場合のみ行うべき」だと強調されている。既存のクライアントが問題なく動作するような軽微な変更（例えば、新しいフィールドの追加など）であれば、バージョンを上げる必要はない。安易にバージョンを上げると、「バージョン肥大化」と呼ばれる状態になり、どのバージョンを使えば良いかクライアントが混乱し、メンテナンスコストが不必要に増大する。

APIバージョンと破壊的変更の間には、明確な「一対一のマッピング（ビジェクション）」が存在すべきだ。つまり、一つのバージョン番号は、特定の破壊的変更のセットと対応しているべきであり、その逆も然りだ。このマッピングが明確であることで、クライアントは特定のAPIバージョンがどのようなデータや動作を提供するかを正確に理解し、安心して利用することができる。もし、破壊的変更がないのにバージョンを上げたり、逆に破壊的変更があったのにバージョンを上げなかったりすると、この大切なマッピングが崩れ、クライアントの混乱や予期せぬランタイムエラーにつながってしまう。

このような「コードの悪臭」は、APIエンドポイントのURLに?version=1のような記述があるかを確認したり、APIの変更後に既存のクライアントが頻繁にエラーを起こす場合に疑うことができる。また、最近ではAIツールも進化しており、エンドポイントのパターンを分析したり、異なるバージョン間のレスポンススキーマを比較したりすることで、クエリパラメータによる不適切なバージョン管理を検出できるようになっている。ただし、AIツールは便利だが、完璧ではないため、最終的には人間の開発者が適切な判断を下すことが重要だ。

結論として、APIの設計においてバージョン管理は欠かせない要素だ。クライアントを破壊的変更から保護し、信頼性の高いAPIを提供するために、適切にバージョン管理を行う必要がある。その際、シンプルで分かりやすい「URLパス」方式を積極的に採用し、「HTTPヘッダー」方式も状況に応じて検討すべきだ。しかし、「クエリパラメータ」を使ったバージョン管理は、将来的な問題を引き起こす可能性が高いため、避けるべきだ。バージョンは、破壊的変更があった場合のみ上げ、古いバージョンは動作させ続けながら、慎重に非推奨化していくプロセスも大切だ。明確なドキュメント作成と徹底したテストも、APIの信頼性を維持するためには不可欠だ。これらのベストプラクティスを守ることで、開発者はメンテナンスしやすいコードベースを保ち、API利用者は安心してサービスを利用できるだろう。皆さんがシステムエンジニアとしてAPIを設計する際には、このバージョン管理の重要性をぜひ心に留めておいてほしい。