バージョン管理

仕組み

APIのバージョンは、クライアントが依存する仕様を区別します。

たとえば、同じ price でも、型を変えると既存の処理が壊れます。

v1

{
  "price": 1200
}

v2

{
  "price": {
    "amount": 1200,
    "currency": "JPY"
  }
}

このような互換性のない変更を、既存利用者に強制しないための仕組みです。

代表的な3方式

いずれも実際に使われる方式です。Microsoftの設計資料でも、それぞれのトレードオフが示されています。Microsoft：APIのバージョン管理

ヘッダー方式とキャッシュ

同じURLでヘッダーにより結果が変わる場合、キャッシュも区別する必要があります。

Vary: API-Version

これは、そのヘッダーの値に応じてレスポンスが異なることを伝えます。CDNなどの設定が、その区別を正しく反映しているかも確認します。

番号の置き場所より重要なこと

実務では、次を決めておく必要があります。

• どの変更を「互換性のない変更」とするか。
• 旧バージョンをいつまで維持するか。
• 廃止予定を利用者へどう伝えるか。
• 旧バージョンの利用者が残っているか、どう確認するか。

フィールド追加も、常に安全とは限りません。未知のフィールドを拒否するクライアントや、列挙値を網羅的に処理する実装では、追加でも問題が起きます。

設計上の要点
バージョン管理の目的は、番号を付けることではなく、利用者が移行できる状態を保つことです。