【ITニュース解説】API Versioning in .NET Web API

APIバージョニングとは、進化し続けるAPI（Application Programming Interface）を管理するための重要な手法である。システムが成長し、新たな機能が追加されたり既存の機能が改善されたりすると、APIの仕様に変更が加わることは避けられない。これらの変更の中には、既存のシステム連携を壊してしまう「破壊的変更」も含まれる。APIバージョニングは、このような破壊的変更が発生しても、既存のAPI利用者（クライアント）が引き続きシステムを利用できるよう、異なるバージョンのAPIを同時に提供する仕組みである。

APIバージョニングが必要とされる主な理由はいくつかある。まず、後方互換性を確保できる点だ。新しい機能を追加したり、データの形式を変更したりしても、古いバージョンのAPIを利用しているクライアントは影響を受けずに動作し続けることができる。これにより、クライアント側での急なシステム改修を強いることなく、スムーズなアップグレードが可能になる。また、どのバージョンのAPIを利用しているかをクライアントに明確に伝えることができ、誤解や混乱を防ぐ。さらに、APIのライフサイクル管理が容易になり、古くなったバージョンを段階的に非推奨にし、最終的に廃止するプロセスを計画的に進めることができる。

.NET Web APIでAPIバージョニングを実装するには、まず必要なNuGetパッケージを追加するところから始める。Microsoft.AspNetCore.Mvc.Versioningというパッケージをプロジェクトに導入することで、クエリ文字列、HTTPヘッダー、あるいはURLセグメント（URLの一部）を使ってAPIのバージョンを管理するためのツールが提供される。

次に、アプリケーションの起動時にAPIバージョニングの設定を行う。これは通常、Program.csファイル内のWebApplication.CreateBuilderやAddControllersの後に記述する。builder.Services.AddApiVersioningメソッドを呼び出し、オプションを設定する。例えば、バージョンが指定されなかった場合にどのバージョンをデフォルトとするか（AssumeDefaultVersionWhenUnspecified = true）、そのデフォルトバージョンをApiVersion(1, 0)のように具体的な値で設定する。また、ReportApiVersions = trueとすることで、APIからの応答ヘッダーに利用可能なAPIバージョン情報を含めることができ、クライアントが現在のAPIバージョンを認識しやすくなる。

実装の効率を高めるための一つの良い方法は、BaseApiControllerと呼ばれる抽象クラスを作成することである。このクラスは、すべてのバージョン管理されたコントローラが継承する基底クラスとなる。BaseApiControllerには、共通の構成、属性、およびヘルパーメソッドをまとめておくことができる。例えば、[Route("api/v{version:apiVersion}/[controller]")]という属性をBaseApiControllerに定義することで、すべての派生コントローラがapi/v1/productsやapi/v2/productsのようにURLセグメントを通じてバージョンを指定するルーティングルールを自動的に継承する。これにより、各コントローラで同じルーティング設定を繰り返す必要がなくなり、コードの重複を避け（DRY原則）、バージョニングロジックを一元的に管理できる。また、ApiResponseのような共通のレスポンス形式を返すヘルパーメソッドもここに実装することで、コントローラ間の振る舞いに一貫性を持たせることができる。

BaseApiControllerが準備できたら、各APIコントローラで具体的なバージョニングを行う。例えば、製品情報を扱うAPIであれば、ProductsControllerには[ApiVersion("1.0")]属性を付与し、バージョン1.0のロジックを記述する。そして、製品情報の取得方法や内容が変更された新しいバージョン2.0を導入する際には、ProductsV2Controllerという別のコントローラを作成し、[ApiVersion("2.0")]属性を付与して新しいロジックを実装する。これにより、URLapi/v1/productsからはバージョン1.0のデータが、api/v2/productsからはバージョン2.0のデータが返されるようになる。

URLセグメントによるバージョニング以外にも、クエリ文字列やHTTPヘッダーを使ったバージョニングも可能である。例えば、GET /api/orders?api-version=1.0のようにURLのクエリパラメータとしてバージョンを指定したり、x-api-version: 2.0といったカスタムヘッダーをリクエストに含めてバージョンを指定したりする方法がある。これらの方法を有効にするには、Program.csのAddApiVersioning設定内でoptions.ApiVersionReaderプロパティを適切に設定する。例えば、new HeaderApiVersionReader("x-api-version")と設定することで、指定したヘッダー名からのバージョン読み取りが可能となる。

APIバージョニングは、古いバージョンを段階的に廃止する際にも役立つ。特定のAPIバージョンが将来的にサポートを終了することをクライアントに通知したい場合、コントローラに付与するApiVersion属性のDeprecatedプロパティをtrueに設定する。例えば、[ApiVersion("1.0", Deprecated = true)]のように設定すると、このバージョンが非推奨であることを示す情報がAPIの応答ヘッダーに含まれるようになり、クライアントは新しいバージョンへの移行を促される。

開発中のAPIやそのバージョンをわかりやすくドキュメント化するために、Swagger（OpenAPI）との連携も非常に重要である。Swaggerは、APIの仕様を自動生成し、対話型のドキュメントとして提供するツールだ。複数のAPIバージョンが存在する場合、AddSwaggerGenメソッドとUseSwaggerUIメソッドをProgram.cs内で設定することで、各バージョンごとに異なるSwaggerドキュメントを生成・表示させることができる。例えば、options.SwaggerDoc("v1", ...)とoptions.SwaggerDoc("v2", ...)のように設定し、options.SwaggerEndpoint("/swagger/v1/swagger.json", "API v1")のようにUIで各バージョンを選択できるようにすることで、開発者は利用可能なすべてのAPIバージョンとその詳細な仕様を簡単に確認できるようになる。

まとめると、.NET Web APIにおけるAPIバージョニングは、Microsoft.AspNetCore.Mvc.Versioningパッケージの導入、Program.csでの初期設定、そしてBaseApiControllerを用いた共通ロジックの集中管理という手順で実現される。これにより、コードの重複が減り、保守性が向上する。URLセグメント、クエリ文字列、またはHTTPヘッダーといった柔軟な方法でバージョンを指定でき、さらにSwaggerとの連携により、多バージョンのAPIであっても開発者が使いやすいドキュメントを提供できる。これらのアプローチを組み合わせることで、進化し続けるシステムにおいて、堅牢で柔軟かつ保守しやすいAPI構造を構築することが可能になる。