APIバージョニング戦略
URL、ヘッダー、クエリ文字列でバージョンを指定します。
「APIバージョニング戦略」はCoddyKit上の無料C# Academyレッスンです。 これはレッスン1/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはC# Academy学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 C# Academyコースには全4レッスンが含まれています。
API をバージョン管理する理由
クライアントが API に依存するようになると、その契約を破壊することはできません。バージョン管理を使うと、互換性を壊す変更を新しいバージョンで提供しながら、古いクライアントは従来のバージョンを使い続けられます。
// v1 returns { name }
// v2 returns { firstName, lastName } (breaking)URL パスによるバージョン管理
最も分かりやすい方法は、バージョンをパスに含めることです。曖昧さがなく、ルーティング、閲覧、キャッシュも簡単です。
GET /api/v1/products
GET /api/v2/productsクエリ文字列によるバージョン管理
バージョンをクエリパラメーターとして渡します。URL は安定したままになり、パラメーターがない場合は最新バージョンまたは固定バージョンをデフォルトにできます。
GET /api/products?api-version=1.0
GET /api/products?api-version=2.0ヘッダーによるバージョン管理
カスタムのリクエストヘッダーにバージョンを含めることで、URL をすっきり保てます。一方で、ブラウザーのアドレスバーからは確認できず、手動でのテストも難しくなります。
GET /api/products
X-Api-Version: 2.0メディアタイプによるバージョン管理
コンテントネゴシエーションとも呼ばれます。バージョンを Accept ヘッダーのメディアタイプに埋め込みます。最も REST に忠実ですが、最も発見しにくい方法です。
GET /api/products
Accept: application/json;v=2.0方式の比較
各方式は、見つけやすさと URL の簡潔さのバランスを取ります。
- URL パス：最も見つけやすい一方、URL が複雑になります。
- クエリ文字列：URL が安定し、デフォルトを簡単に設定できます。
- ヘッダー：URL はすっきりしますが、ブラウザーからは見えません。
- メディアタイプ：最も純粋な REST ですが、最も扱いにくい方法です。
// Many teams pick URL path for public APIsAPI のセマンティックバージョニング
API のバージョンは通常、メジャーのみ（v1、v2）で管理します。マイナーバージョンは、古いクライアントが無視できる、追加的で互換性を壊さない変更のために使用します。
// v1.0 -> v1.1 : additive (safe)
// v1 -> v2 : breaking (new version)非推奨化
古いバージョンを突然削除してはいけません。非推奨としてマークし、提供終了日を告知して、ヘッダーでクライアントに知らせます。
// Response header on a deprecated version:
// Sunset: Wed, 31 Dec 2026 23:59:59 GMT
// Deprecation: trueデフォルトバージョン
クライアントがバージョンを指定しなかった場合の動作を決めます。よくある選択肢は、最新バージョン、v1、またはリクエストの拒否です。動作を明示すると、予期しない問題を避けられます。
// Strategy: unversioned request -> treat as v1.0適切な対象のバージョン管理
内部実装の詳細ではなく、契約（ルート、リクエストおよびレスポンスの形式）をバージョン管理します。v2 のエンドポイントでも、ビジネスロジックの大部分を v1 と共有できます。
// Same service, two thin controllers:
// ProductsV1Controller, ProductsV2Controller方式の組み合わせ
ASP.NET Core のバージョン管理ライブラリでは、複数のソースから同時にバージョンを読み取ることができます。クライアントは都合のよい方法を選択できます。次に、この設定方法を説明します。
// Accept version from URL OR header OR queryクイックチェック
バージョン管理の方式についての理解度を確認しましょう。
まとめ
API のバージョン管理方式について概観しました。
- URL パス、クエリ文字列、ヘッダー、メディアタイプがあります。
- 各方式は、見つけやすさと URL の簡潔さのバランスを取ります。
- 契約をバージョン管理し、適切に非推奨化し、デフォルトを定義します。
次は、ASP.NET Core での Asp.Versioning の設定です。
よくある質問
「APIバージョニング戦略」レッスンは無料ですか？
はい。「APIバージョニング戦略」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、C# Academyコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 C# Academyコースには全4レッスンが含まれています。
「APIバージョニング戦略」で何を学びますか？
URL、ヘッダー、クエリ文字列でバージョンを指定します。 ブラウザで直接実行するハンズオンコードでC# Academyを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。
C# Academyを始めるのに経験は必要ですか？
事前経験は必要ありません。CoddyKitのC# Academyは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン1/4です。
「APIバージョニング戦略」レッスンにはどのくらい時間がかかりますか？
ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。
このC# Academyレッスンでコードを書いて実行できますか？
はい。すべてのC# Academyレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。