5.2 API をバージョンで管理する

問題回避の最も良い方法は、一度公開した API をできる限り変更しないこと。
新しいエンドポイントや別のパラメータを付けた URI など、何らかの新しいアクセス形式で公開を行う。
=> 古いクライアントは旧 API を利用し、新しいクライアントは新 API を利用できる。

新旧の API を共存させる方法として API に何らかの形式でバージョン番号を振っていく。

サービス	エンドポイント
Twitter(旧バージョン 1)	`http://twitter.com/statuses/user_timeline.xml`
Twitter(新バージョン 1)	`https://api.twitter.com/1/statuses/user_timeline.json`
Twitter(バージョン 1.1)	`https://api.twitter.com/1.1/statuses/user_timeline.json`

URI のパスの一番先頭にバージョン番号を埋め込む。v1 のようにバージョン番号であることを示す v を付けることもある。

基本的は API のバージョンは簡単に上げるべきではないため、整数でカウントアップしていく。
セマンティックバージョニングとは異なる。
小さな変更は後方互換性を担保して対応し、後方互換性を失うほど大きく重要な変更を行う場合のみバージョンを上げる。

http://api-public.netflix.com/catalog/titles/series/703?v=1.5

パスに埋め込む場合と異なり、クエリ文字列の時は省略が可能。省略した場合はデフォルト（最新版が多い）のバージョンが利用される。
指定を省略しているユーザーがバージョンアップの際に自動的に最新版 API を利用することになり、問題が発生する可能性がある。

クライアント側
- バージョン番号を含むメディアタイプを指定する
- Accept: application/vnd.exmple.v2+json
サーバー側
- サーバー側はレスポンスの際に Content-Type, Varyヘッダ を付ける
- メディアタイプによってレスポンスが変わるのでキャッシュの際に Acceptヘッダ の考慮が必要
- Content-Type: application/vnd.example.v2+json
  Vary: Accept

クライアント側のライブラリによっては独自メディアタイプは正常に認識していもらえない可能性がある。
→独自の HTTP ヘッダを定義して、そのヘッダを用いてバージョン指定する方法もある。

どの方法も一長一短。
URI パスにバージョンを含める方法が最も広く利用されている。