そのAPI、バージョン管理が必要ですか？

APIを設計する上でバージョン管理をどのように行うかは常に頭を悩ませる問題です。しかし、そもそもバージョン管理が必要なのでしょうか。今回はそんな問題提起と、その解決策の紹介です。

結局バージョン2が出てこない

APIのあるある問題として、バージョン管理を盛り込んだのはいいけれど、結局新しいバージョンが出てこないという問題があります。いつまでも/v1/のまま運用していないでしょうか。ムダにURLを長くしてしまっているだけの可能性があります。

ポリシーが不明確

v1のまま運用しているからといって、APIが全く更新されていないかといえばそうではありません。多くのサービスはきちんと運営されており、APIもそれに合わせて更新されています。しかしv1に機能追加という形で行われている場合がほとんどです。

問題はどういった場合にv2にするかというポリシーが不明確であるということです。バージョンを上げる理由をきちんと作らなければならないのですが、あまり頻繁にあげると開発者を混乱させる可能性があったり、過去バージョンのレスポンスをサポートし続けなければならないといった運用上の問題も出てきます。

一部だけ更新はありえない

さらに一部の機能だけ v2 になるということはありません。開発者としてもある機能を呼ぶときだけ v2 を、それ以外は v1 を呼ぶというのは非常に面倒になります。そこで基本的に全機能が v2 となっても利用でき、一部の機能だけ v2 として提供されるのが一般的です。つまり古い機能についてはエイリアスになります。

その場合、ドキュメント整備の問題があったり、実際には v1 と v2 の機能が同じなど開発者を混乱させてしまう可能性があります。

解決策

APIのバージョン管理については幾つかの方法がありますが、多くの場合開発者や、その開発者が使っているアプリごとに使いたいバージョンは決まっているという事実があります。そこで、利用するAPIのバージョンを設定画面を使って指定してもらうという方法が考えられます。

そうすることで、URL上からはバージョン番号を消すことができます。常に同じURLにアクセスするので利便性が高まるでしょう。また、運営側としてもどのバージョンのAPIが使われているかを管理しやすくなり、過去バージョンのAPIに対する保守管理を行うかどうか判断しやすくなります。

または思いきってバージョン管理を考えないという方法も考えられます。おそらく殆どの場合において、バージョン管理は利用されません。であれば、常に同じエンドポイントをメンテナンスし続ける方が安心ではないでしょうか。バージョン番号による余計な分岐処理はコードを見づらくしたり、後方互換性における開発コスト増につながります。そういった余計なコストをなくせるようになるでしょう。

適切なAPIのバージョン管理は適切なポシリーがあってこそ成り立つものです。もしバージョン管理を設計に含めるのであれば、まずポシリーの設定が求められるでしょう。