OpenStack Apiのバージョニング規約に言及しながら、Mark Nottingham氏がクラウド上のウェブAPIの様々なバージョニング戦略について分析している。氏が言うにはソフトウエアのバージョニングとウェブのバージョニングとを比べるとソフトウエアのバージョニングの方が進んでおり、理解もしやすい。
開発者はバージョンを打ちます。例えば、各リリース毎にバージョンを上げます。普通はメジャーバージョン、マイナーバージョンを使いますが、パッケージ識別子のようなものを使う場合もあります。このバージョンの粒度は開発者にもユーザにもとても使いやすいです。互換性やデバッグなどで利用するのに十分に正確な意味を提供してくれるからです。
しかし、氏によれば、ウェブAPIのバージョニングはこのアイディアのバージョニングを上手く取り込めていないという。
[クライアントが]以前のバージョンのAPIが提供するリンクを使い続けている場合、クライアントは将来どうするか決める必要があります。前のバージョンと今のバージョンで互換性があると推測することもできますが、確証はないので、APIのブランチを記述する必要があります。
[…] ソフトウエアのバージョニングの方法をウェブのURLに持ち込むとHTTPを使うことの価値がなくなってしまいます。それは‘無能な’RPCプロトコルを使うのと同じです。
氏によれば、ウェブのバージョニングというテーマは既存のクライアントの互換性を維持することだ。
基本的な原則は既存のクライアントとの関係を放棄できないということです。クライアントがどのような実装か分からないし、制御もできないからです。
さらに次のように付け加える。
[…] [ウェブの]バージョニングは本質的に非線形です。言い換えれば、新しい識別子を打つときは、根本的に新しい物を打つということです。それは、HTTPヘッダーかもしれませんし、メディアタイプて指定されるフォーマットかもしれませんし、URIかもしれません。“foo”や“bar”と“v1”や“v2”として使うのもいいでしょう。
氏はhttpヘッダーを使った拡張的な仕組みの利点を活用する様々な方法を事例を交えて紹介している。そして、プロダクトトークンを使うことで識別し、実装の問題を解決する方法を支持している。
氏はウェブのバージョニングをふたつのカテゴリに分類する。フォーマットの変更とリソースの変更だ。
フォーマットの変更はかなりしっかりとした紹介があります(例えばDave)。この方法はシンプルでもあり恐ろしいほど複雑でもあります。一言で言えば、後方互換性を維持した変更はできません。もし、実現するなら、メディアタイプを変える必要があります。
一方、氏によればリソースの変更はより興味深い問題を孕んでいる。よく試行錯誤されている方法はUriをバージョニングする方法だ。これに比べるとハイパーメディアを使う方法はあまり一般的ではない。
RESTafarianは長い間、ウェブAPIにHATEOSの印を探しています。Royは大多数のウェブAPIにHATEOSが無いことを嘆いています。
氏は、どうやってハイパーメディアを使ってサービスが提供する様々なリソースのテンプレートを提供することでクライアントがUrlを生成するのを支援するメタリソースを公開するかを説明している。
この方法だと、インターフェイスに異なるURIを必要としません。エントリポイントがエージェント駆動のコンテンツネゴシエーション向けに効果的に使われるからです。
氏はHATEOASを使う方法には賛成も反対もあることを認めている。しかし、この方法が提供する拡張性はこの方法を戦略的に使うためのしっかりとした理由になる。
私が考えるに、重要なのはURIが本当にたくさんのことに使われているということです。— 識別子であったり、キャッシュのキーであったり、相対パスの解決や、ブックマークにも使われています。さらにバージョニングや拡張可能な情報をURIに担わせるのは負担になりすぎますし、これら目的に照らし合わせても良いことではありません。この関心事をHATEOSを使ってリンクの関連やメディアタイプに押し込むことで、HTTPのメリットを捨てることなく制御可能な方法で成長させられる柔軟で古びないシステムが実現できます。
元の分析は氏のウェブサイトで閲覧できる。