Web APIにバージョンをつけないように

URIにバージョンを付与したり、バージョン付きのmedia typeを使用することによりWeb APIにバージョンを付与するのはオープンWebにおいては機能しない。むしろ必要とされているのは必要とする変更を行いながら進化していくための規則である、とSebastien Lambla氏は最近のプレゼンテーションで主張し、バージョンを付与する必要を避ける方法を述べた。

RESTアーキテクチャスタイルのコンサルタントであり信奉者のLambla氏によれば、Web APIのバージョニングの共通した理由はAPIのクライアントの動作を破壊しないために用いている規則に起因する。クライアントとサーバがそれぞれ独立に変更させ、クライアント開発者にAPIの変更に関するやりとりができるのが望ましい。Lambla氏によれば、バージョニングは結合度、本質的には変更の制御を管理する基本的な方法をなのである。

バージョニングの一つの方法として、次のようにURIにバージョンを加えることが考えられる。つまり、http://api.equestrian.magic/v1/のような形式である。リソースのURIを変更するときの一つの問題は、リダイレクトしない限り古いURIではリソースが見つけられなくなることである。Lambla氏は、リソースのURIはずっと変更されるべきではないが、新しくバージョンを付けるとあるリソースに対して2つURIが存在してしまうことになってしまうことを強調する。これは、普通は異なる二つのものが存在し、これらが互いに関連する可能性はないということを表すのである。

上記の代替として、ドメイン名にバージョンを付与することが考えられる。つまり、http://v1.api.equestrian.magic/のような形式でである。URIは不透過であるため、実際には別の新しいシステムを作り出したことになる。複数のシステムとモデルではあるが、同じデータモデルを指す状態になるため、メンテナンスの困難さが増すことになる。

第3の代替はmedia typeにバージョンを付けることであり、Lamblaは今日のWebではあまり見られないとLamblaは考えているが、これはエンタープライズにおいてはまだ非常に用いられている方法である。この方法はコンテントネゴシエーションに基づき、AcceptヘッダとContent-Typeヘッダのmedia typeにバージョンを付与する。つまり、application/vnd.equestrian.ponies.v1+xmlのような形式でである。Lamblaは、異なるバージョンもまた実質的に異なるリソースであり、異なるmedia typeを同一のURIに用いることはリソースの同一性を破壊すると主張する。彼は主張の根拠としてRoy Fieldingを引用している。

形式間の差異が性質上機械的なものである場合にのみ、リソースオーナには(リダイレクトを行わない)本当のコンテントネゴシエーションを推奨する。

Lambla氏によれば、これらのバージョニング技術のいずれもオープンWebでは機能しない。本当に求めているのは要望が変化するのに伴いスムーズに進化可能な規則を用いて進化することができることなのである。これはよく知られた問題であるとLambla氏は述べており、Webを見てみると非常に多くのマイクロサービスが、HTTPを除きバージョニングせずとも25年以上大きな問題がなく運用されている。

進化可能な規則の第1の根幹部分は後方互換性である。Lambda氏はHTMLを例示し、使用を推奨されない多くの要素が存在するものの、世界中の全てのWebサイトを更新することはできないためまだサポートされていることを説明している。同じ原則はAPIにも適用されるべきである。つまり、古い形式をサポートしながら進化していくのである。

第二の柱は前方互換性である。このことを達成するために、知らなかったり、理解できないものを無視する必要がある。Lambda氏はCSSを引用し、新しい属性が問題なく扱えることを示した。このことを達成するために、知らない属性を扱うために用いられる縮退ルールが用いられており、拡張ポイントを得るための重要な方法となっている。

XMLはいまだによく用いられており、XMLスキーマと共に用いられることもしばしばである。進化可能性をサポートするためにはコンテンツは柔軟であるべきあるため、Lambla氏はクライアント側と同様にサーバ側でもスキーマ検証を行わないことを強く勧めている。代わりに、必要としている要素や属性だけを見つけて他は無視するのである。

バージョニングを避けるためには全ての機能をサポートし続ける必要があるが、APIの全ての変更を永遠に保つのは不可能である。ほとんど用いられない古い機能は削除されるべきである。いつ削除されるべきかを知るために、基準値を用い使用方法を測定する必要がある。例えば1%以下などに使用率が落ちたとき初めて 、機能を削除してもよいと判断できるのである。