APIのバージョンアップにおける問題点とは？

APIは作って終わりではなく、徐々に機能追加したり問題があればフィックスをします。それを繰り返す内に起きるのがバージョンアップ問題です。今回はAPIのバージョンアップに絡んだ問題と、その解決策を紹介します。

URL設計

将来のバージョンアップを予期したURL設計にしておくのは大事です。よくあるのは /v1/からURLをはじめるパターンです。これを忘れていると、URLの中に無理矢理入れることになります（/users/ と /users_2/ といった具合に）。

いつをもってバージョンを変えるか悩む

これが最も良くある問題ではないかと思います。ちょっとした機能追加でバージョンを上げてしまうと、今後繰り返されるちょっとした修正のたびにバージョンが上がってしまって管理しきれなくなります。かといっていつまでもバージョンアップしないといつまで経ってもv1のままで、何のためにバージョン番号をつけたのか分からなくなってしまうでしょう。

結局のところポリシー次第なのですが、注意点としてはバージョンが変わるとこれまでの既存のAPI全体を作り変える必要があるということです。少なくともコピーすることはできますが、インタフェース設計が変わっていたりすると全体のバランスが崩れてしまいます。

コストがかかる

ということはAPIのバージョンが変わると、全面的に作り変える必要が出てくるのです。そのためバージョン1はSOAP、バージョン2はRESTfulなど技術的なパラダイムシフトが起こった、またはアーキテクチャが変わったタイミングでバージョンアップするのが良いかも知れません。

後方互換性を維持するべきか

利用者のことを考えると後方互換性は維持されているのが良いでしょう。サポートとしても、ある機能が使えないときに、それがバージョン1に起因するものなのか、違うのかに判断が困るかも知れません。

ただし後方互換性の維持はモダンな実装の足かせになったり、開発やテストコストの増加につながります。さらに利用しているライブラリをバージョンアップしたタイミングで古いバージョンの動作が変わったりする可能性があります。そのため、できればサーバ自体を分け、過去のAPIについてはノータッチにするというのが安心かも知れません。

古いAPIをいつまでサポートすべきか

API連携のシステムは一旦開発するとそのまま放置されるのが一般的です。そのため古いAPIが使えなくなるといったアナウンスをすると、補修が発生します。しかし数年前のシステムを完全に把握しているというのは稀でしょう。

そのため新しいAPIリリース後、1年くらいの猶予は必要だと思われます。しかし多くのケースではうまく乗り換えできず、そのままずるずると古いAPIのまま続いてしまっています。特にB to Bで提供されているAPIではその傾向が強くあります。あらかじめ契約時にその旨（APIのバージョンアップがあること。古いAPIについては段階的に廃止されていくなど）を追加しておくのが良いでしょう。

あらかじめAPIを利用するライブラリを提供しておき、直接APIを触らないようにしておきましょう。そうすることでライブラリのバージョンを変えれば既存のシステムには手を加えずに新バージョンに対応できるようになります。

オープンソースではメジャーバージョンアップしたタイミングで過去の資産をすべて切り捨てることもありますが、多くの場合は継続して利用されます。それを参考にして考えると、バージョン2にアクセスしても既存の機能はそのまま使える方が安全かも知れません。その中で技術的負債になってしまっている機能については推奨せずであったり、期日をもって閉鎖とするのが良いのではないでしょうか。