バージョンアップはするな！というのが原則です。

なぜバージョンアップは避けないといけないのか

APIを使っているAPIクライアント側の開発チームがついてこられるかわからないからです。特に外部のAPIクライアントをサポートする外部公開されたAPIや、社内であってもプロジェクト予算が別についているAPIクライアントは、APIのバージョンアップがあると追従するか、他に差し替えるか、あるいはAPIクライアントそのものをリタイアさせるかの選択肢を検討することになります。ひいてはAPIクライアントのユーザーを失うということにつながります。

バージョンアップを避けたい理由: Twitter APIバージョンアップケーススタディ

なぜそんなことになったのかは2012年から2013年に行われたTwitterのAPIのバージョンアップの顛末を追いかけると明らかです。

Twitterのアナウンスへのリンクは別記事を参照いただくとして、ではこの顛末がどういう学びにつながったかというのをご説明したいと思います。

バージョンアップ前のことを触れておきますと、TwitterのAPI公開はTwitterユーザーの拡大に寄与したと言っていいと思います。

古いバージョンのAPIがまだ公開されていた頃は、ちょうどスマートフォンが登場し、ネイティブアプリという領域が出てきた頃です。一般のアプリケーション開発者の多くがネイティブアプリなるものの領域を知り、作ってみたいと思っていました。そこに対してTwitterはAPIを公開されたので、ネイティブアプリに興味がある開発者の多くがTwitterアプリを作ったんです。当時のApp StoreなどでTwitterを検索すると、たくさんのTwitterアプリがヒットしました。TwitterはAPIを公開することで、利用者の好みのインターフェースを選べる状況を作ったんですね。

その状況下で2012年にTwitterがTwitter APIのバージョンアップをすると発表しました。2012年9月に新しいバージョンをリリースし、半年後の2013年3月のリタイアを宣言しました。
予定通り2013年3月にブラックアウトテストを実施、古いAPIにきたリクエストに対してエラーを返すように設定し、どの程度が移行済みか影響を把握しようとしました。

余談ですがこの辺は現在API Gatewayでメトリックで把握できる領域なので、今はこのようなやり方はしなくてすみます。

ブラックアウトテスト実施の結果、多くのクレームが寄せられました。そもそもAPIのバージョンアップそのものを知らなかった、そもそもバージョンアップがあるものだとは思っていなかったとAPIクライアントの開発者がコメントされているのを、今でもオンラインのディスカッションボードなどで読むことができます。

結果的にリタイアを延期し、何度かブラックアウトテストを繰り返した結果、やっと古いバージョンのAPIはリタイアできました。

APIバージョンアップによりAPI提供側に発生するデメリット

よくあるパターンとして、以下のようなリスクが発生します。

• APIクライアントごと利用者を失う

• バージョンアップのためのサポートコスト

• APIが拡張できないことによるビジネスの拡張難易度の向上

• アグリゲーションの層で吸収することを選択した場合、アグリゲーションのバリエーションの増加によるメンテナンスコストの増大

社内のAPIであれば以下のようなデメリットの出方をすることがあります。

• APIクライアントの開発費用が別立てなので、APIクライアントに予算がおりずバージョンアップに追従できない

• バージョンアップできないので複数バージョンをずっとメンテしないといけなくなる --> メンテナンスコスト

バージョンアップ戦略

外部公開、あるいは社内であっても多くのAPIクライアントが使うことが想定されるAPIであれば、あらかじめAPIのバージョンアップは行われるものだという期待値を立ててしまう方針が見受けられます。

例えばTwitterの広告APIではあらかじめバージョンアップの頻度やEOLポリシーを公開されています。

eBayではAPIをアルファの段階から開発者に参加してもらってフィードバックを得るようなバージョン戦略をとっています。これは非常に良いアプローチです。バージョンアップに対する興味をデベロッパーに持ってもらうこと、およびアルファやベータ段階で多くのフィードバックを得ることでより質の高いAPIを公開しようという意図ではないかと思います。

バージョンアップを最小限にするための設計方針

破壊的変更が発生しにくいように設計しておくことです。

よくやるアプローチとしてデータベースのスキーマをそのまま吸い上げてAPIにするアプローチがありますが、これはセキュリティ的にもバージョン戦略的にもあまりお勧めできません。

APIのリクエストBodyやレスポンスBodyから属性を抜く、あるいは属性のラベルを変更することは破壊的変更になりますが、追加することは破壊的変更になりません。したがって最小限の属性をデフォルト公開することを考えてみると良いかと思います。

また「使い勝手」に関してはAPIクライアント開発者の観点をお持ちの方に協力いただき、ユーザーテストを複数回実施し、あらかじめ使い勝手の不具合は削減しておくことをお勧めします。

セマンティックバージョニング = バージョン番号の採番ルール

バージョン番号の採番ルールは現在セマンティックバージョニングが一般的です。詳細はこちらをご参照ください。

新旧バージョンをどこで実装するか

アプリケーション次第です。

サイズの大きなバックエンドAPIであれば、バックエンドAPIのコードの中に実装せざるを得ないでしょう。デメリットはコードが複雑になること、および旧バージョンのリタイアにメンテナンスが必要であることです。

別バージョンを別のノードで実装しても良い場合はその方がやりやすいと思いますし、リタイアも簡単です。API Gatewayやサービスメッシュでは、APIクライアントがAPIをリクエストしたURLやヘッダーを参照しながらルーティング先を選択する方法がありますので、別ノードで実装するとリタイアも簡単にできます。設定を削除すれば良いからです。

ただし選択したテクノロジーによりバージョンアップの柔軟性がきまってきますので、あらかじめどの程度のバージョンを並行稼働したいか、リタイアをどのようにしたいかなどにより採用するテクノロジーを選択する必要があるかもしれません。