APIのバージョニングについて考える
はじめに
WebAPIを作る際にAPIのバージョンニングをエンドポイントに含めることがよくある。 これについてなぜやるのかをまとめてみる。
バージョニングとは
いくつかの種類があるようだが、イメージとしては以下のようなエンドポイントにv1などの バージョン情報が付与されているものを指す。
https://example.com/v1/foo/ https://example.com/v2/bar/
バージョニングの種類
いろいろ流派があるようだ。
URIにバージョンを埋める
上記にも書いたが以下のようなものを指す。
https://example.com/v1/foo/
個人的にはこれを使って実装している。
host名にAPIバージョンがある
以下のようなものを指す。
https://api-v1.example.com/foo/ https://api-v2.example.com/foo/
上記のようにサブドメインにバージョンを含めるパターン。 これは実際にやったことはないが、DNSを都度設定するのが大変？
headerに入れる
以下のようなものを指す。
https://example.com/foo/ http headerに以下のように version:v1
これも実際にやったことがない。 エンドポイントにバージョンがないのでスマートのように見える。 疎通確認でheaderに設定を入れるのを忘れない意識が必要か。
どの方法を選ぶか？
自分の経験としては「URIにバージョンを埋める」の方法のみしか実践したことがない。
バージョンにvを含めるか
バージョニングする際にvを含めるかどうかを判断する必要があるかもしれない。 ここでもまずは個人的な経験範囲でいうと、vを含めて開発している。 理由を考えたことがなかったが、「Web API: The Good Parts」にわかりやすく意見が書いてあった。 P143から引用する。
筆者はvをつけるほうが好みです。なぜならそれがバージョンである、ということがはっきりわかるからです。
バージョニングのメリットとデメリット
メリット
APIを呼び出すクライアントの変更が容易にできない場合にバージョニングしておくことで 互換性を保つことができる。
例えば呼び出しているのがスマホアプリだった場合はアプリのアップデートが必要になる。 その場合に呼び出すAPIの改修をしてしまうと、アップデートをしないユーザのアプリが予期していない動きになる。
このようなケースの場合にバージョニングしていることでアップデート前のアプリの前は前のバージョンのAPIを参照、 アップデートしたユーザのアプリはアップデート後のAPIを参照することで後方互換を保つことができる。
デメリット
デメリットはバージョンごとに管理する必要がでてくること。 これは内部のロジックでこのバージョンの場合はこの処理みたいな分岐がでてきて 処理が複雑になる可能性がある。
まとめ
APIの開発をする際に何気なくバージョニングをしていたが、APIのクライアントの事情を考慮する必要がある場合に 有効な手段だと思う。 その際にAPI側でバージョンごとにロジックが複雑にならないようにするテクニックが必要だと思う。
参考資料
書籍
WEB
バージョニング | Cloud API | Google Cloud
ほしい
持っていないが気になっている本。いつか書く。 Web APIの設計 (Programmer's SELECTION)
