はじめに
WebAPIは、上手く使えばWebサービスを連携させることができるので非常に便利ですが、いざその設計をするとなると、UIを備えたWebアプリケーションとは違う観点が必要になります。
今回は、WebAPIの設計をするにあたってよく議論になる（かもしれない）バージョン管理の考え方について書いていこうと思います。
なお、WebAPIとはなんぞや？とか、RESTの原則が、とかいう話は一切出てきません。
バージョン管理とは
URLに /v1/users とか付いてるやつ、よく見ますよね。
状況によっては「バージョン管理なんて無い方が良い」とか「永遠のv1」とかもあり得るかも知れませんが、拡張のためにあった方が良い場面も多いです。
なぜバージョン管理が必要か？
基本的に一度リリースしたWebAPIは、その中身を変更しようとするとそのAPIを使っているシステム（APIユーザ）にも影響が出てしまうため、不具合を除けば変更しないことが望ましいです。
ただそうは言っても、不具合だったり機能拡張だったり大人の事情だったり、改修を加えたいということが発生するかもしれません。
このときに、その改修内容が、 【後方互換性があるかどうか】 というのを、WebAPI開発では気にする必要があります。
「後方互換性」を簡単に言い換えると、現行のWebAPIを使っているAPIユーザが、自分のプログラムを変更することなくその変更を受け入れられるか、ということになります。
例えば、リクエスト形式・レスポンス形式に全く変更がない場合は、APIユーザはそのまま自分のプログラムを使い続けても問題ありませんね。
リクエストに一つパラメータが追加された、くらいでもおそらく大丈夫なことが多いでしょう。
しかし、レスポンスの形式が大きく変わってしまったり、今まで存在していたパラメータがなくなってしまう場合、リクエストに必須のパラメータが増える場合などは、APIユーザのプログラム側も変更してもらわないといけなくなります。
この場合は、バージョンを v1 → v2 などに変更することで、既存機能は残してそのまま使い続けてもらいつつ、APIユーザに対して変更内容を周知した上で、プログラムを変更して移行してもらうことが必要になります。
特に、APIユーザが自分たちのチームの管轄外である（リリースタイミングが制御できない）場合は、バージョン管理は必須と言えるでしょう。
有名所のWebAPIでも、URLにバージョン管理の文字列が付いているところが多いですね。
バージョン情報はどうやってつける？
バージョン情報の表現方法は、だいたい以下の4つのいずれかになることが多そうです。
-
2019-12-04のような日付形式 -
v1.2.3のようなセマンティックバージョニング形式 -
v1.2のようなメジャーバージョン.マイナーバージョンの形式 -
v1のようなメジャーバージョンだけの形式
※ セマンティックバージョニングとは・・・ https://semver.org/lang/ja/
APIの規模や改修頻度にもよりますが、大体の場合は3か4で事足りるのではないでしょうか。
ただし、どんなときにバージョン変更を行うかはあらかじめ決めておく必要があります。
また、やたらにバージョンを増やしてしまうと、その分管理コストも増えてしまうのでオススメはしません。
バージョン管理の単位は？
ここは悩みどころだと思います。
本来であれば、 v1 にすべての機能が網羅されており、 v2 にバージョン変更しても同じようにすべての機能が網羅されている、という形の方がすっきりしているように見えますが、この形だと、一部の機能だけ後方互換性のない変更を行いたいにもかかわらず、すべての機能に対してバージョン変更が必要になってしまいます。
そこで、機能（エンドポイント）ごとにバージョン管理を行う、という形を取ることがあります。
または、メジャーバージョンはAPI全体に関わる変更（認証方式の変更やレスポンス対応形式の変更など）、マイナーバージョンは機能ごとにアップデートしていく、という形も考えられます。
例えば、以下の2つのエンドポイントがあるような状況で、
/v1.0/users
/v1.0/companies
users側にのみ変更があった場合は、
/v1.1/users
/v1.0/companies
のようにバージョン管理をしていく形になります。
すべての場合でこれがベストだとは思いませんが、何か改修がある時は各エンドポイント単位で行われることが多いと思いますので、バージョン管理もそれに即した形式にするのがやりやすいかなと感じています。
もちろん、あらかじめルールを決めた上でAPIユーザに周知しておく必要はあります。
余談ですが、ココらへんのバージョン管理を踏まえたクラス設計は、設計者の腕の見せどころですね...！
もっと詳しくは
Web API: The Good Parts
https://www.oreilly.co.jp/books/9784873116860/
API設計に関わることになった、という方は、是非これを一読することをオススメします。
本記事のバージョン管理の話ももちろん書かれていますし、設計として抑えておくべきことや考え方も含めて、網羅的・実践的に書かれていて非常に読みやすいと思います。
（宣伝ではないですw）
あとがき
機会があれば他のハナシについて書くことがあるようなないような。