Ejima)でも本件に言及があったようなので、少し一般論を書いておきたいと思います。一般的に、以下の2点が挙げられると思います。拡張が容易である拡張時に後方互換性を破壊しないウェブの場合は、これに加え、スケーラブルであるHTTPに起因する問題に上手に対処できることが求められます。前2者はウェブに限らない要件です。これを満たす設計手法としては、リクエストおよびレスポンスのパラメータを拡張可能に互換性を壊す拡張が必要な場合は、関数名を変える古い関数は従来と同じ機能を提供するステートフルAPIは、抽象データ型の使用といった手法が一般的です。WindowsのAPIを見ると、多くのリクエストとレスポンス型が拡張可能であり(cbSizeというフィールドで拡張領域を指定する)、非互換な拡張がされたAPIは「〜Ex」という名前をもっており、ステートの表現にはHANDLEという抽象データ型が使われていることが分かります。これに対し、後2者はウェブ固有の色合いが強い要件です。そのための設計手法として、(出来る限り)ステートレスなAPI冪等性に対する配慮が求められる、ということが知られています(したがって、「ステートフルなAPIにおける抽象型の利用」という一般的な設計手法は検討対象外となる)。APIを設計する基本原則として、以下の4点を採用するのが良い、ということになります。拡張可能なパラメータJSONのような拡張可能なシリアライズフォーマットを用い、拡張可能な形で入出力パラメータを設計する互換性を壊す必要がある場合は関数名を変更するできるだけステートレス冪等性に対する配慮よく分からなければ、とりあえずRESTを使うこのような設計をとっていれば、APIを拡張しても後方互換性を確保することができますし、バージョン番号による分岐も必要になりません。APIの設計において、バージョン番号による分岐という概念は必ずしも必要なものではありません。実際は、それでもバージョン番号をURLに含めるべきだと考えられることがあります。APIが拡張(ないし変更)されていくということは、すなわち、サーバサイドの提供するAPIの「バージョン」とクライアントアプリケーションが期待するバージョンの齟齬による互換性問題が発生しうるということを意味します。そのような互換性問題は、実行中の良くわからないエラーではなく(データ保存しようとしたらエラーとか最悪ですね!)、明確にトラブルシュートできる、つまり、起動時のバージョンチェックで検出され、ユーザーや管理者に明確に通知されることが望ましいということになります。実際には、以下のような要件のもとで、確実に機能するバージョンチェック機構が望ましいということになります。クライアントが「廃止された」APIに依存しているかどうかは、サーバサイドでないとチェックできないクライアントアプリケーションの開発者は、しばしば「バージョンチェックを怠る」もうお分かりでしょうか。この要件を最も単純に実現する手法が、APIのURLにバージョン番号を含めるという手法なのです。APIに対する全てのリクエストにバージョン番号が含まれるため、「クライアント側でバージョンチェックを怠った」がゆえのエラーは発生しようがありません。サーバサイドのログにもバージョン番号が残るため、管理者の側で問題の切り分けを要求された場合にも、対処することが容易です。これが、バージョン番号をAPIのURLに含めるべきと考えられる理由です。全ての条件において必要ではないかもしれませんが、一考に値するのではないでしょうか。蛇足ですが、APIのバージョニングについては、サービスとしてしか提供しないソフトウェアの場合は、後方互換性を崩す度にバージョン番号の変更が必要です。サーバをソフトウェア製品として提供する場合には、機能拡張を行う度にバージョン番号の変更が必要になります注1(2014/3/11加筆)。versioningを参考に、MAJOR.MINORのような記法を採用するのが望ましいと言えるでしょう。