[解決済み] API のバージョン管理に関するベストプラクティス？[クローズド］

質問

WebサービスREST APIのバージョン管理について、既知のハウツーやベストプラクティスはありますか？

私は、以下のことに気づきました。 AWSはエンドポイントのURLでバージョニングを行う . この方法しかないのでしょうか、それとも同じ目標を達成する他の方法があるのでしょうか？複数の方法がある場合、それぞれの方法の利点は何ですか？

解決方法は？

これは良い質問であり、また厄介な質問でもあります。のトピックは URIデザインは と同時に REST APIで最も目立つ部分であり したがって、潜在的に そのAPIのユーザーに対する長期的なコミットメント .

アプリケーションの進化、さらにそのAPIの進化は、プログラミング言語のような一見複雑な製品の進化と似ているとさえ言える事実であるため URI設計 は少ないはずです。 自然な制約 そしてそれは 時間をかけて保存されるべき . アプリケーションやAPIの寿命が長ければ長いほど、そのアプリケーションやAPIの利用者に対するコミットメントが大きくなります。

一方で、APIを通じて消費されるであろうすべてのリソースとその側面を予見することは難しいということも事実です。幸いなことに、次の段階まで使われるであろうAPI全体を設計する必要はない。 アポカリプス . すべてのリソースエンドポイントと、すべてのリソースとリソースインスタンスのアドレス指定スキームを正しく定義すれば十分です。

時間が経つにつれて、新しいリソースや新しい属性をそれぞれの特定のリソースに追加する必要があるかもしれませんが、リソースのアドレス指定スキームが公開され、したがって最終的になったとしても、APIユーザーが特定のリソースにアクセスするために従う方法は変わってはいけません。

この方法は、HTTP動詞のセマンティクス（例えばPUTは常に更新/置換されるべきである）と、以前のAPIバージョンでサポートされているHTTPステータスコード（それらは、これまで人の介入なしに動作してきたAPIクライアントがそのように動作し続けることができるように、動作し続けるべきである）にも当てはまります。

さらに、APIバージョンをURIに埋め込むと、「URIのバージョン」という概念が崩れるので、「URIのバージョン」を「URIのバージョン」と呼ぶことにした。 アプリケーションの状態のエンジンとしてのハイパーメディア (Roy T. Fieldings博士論文に記載) 時間と共に変化するリソースアドレス/URIを持つことによって、私は次のように結論づけます。 APIバージョンはリソースURIに長期間保持すべきではない というのは APIユーザーが依存できるリソースURIはパーマリンクであるべきです。 .

もちろんです。 ベースURIにAPIバージョンを埋め込むことは可能です。 しかし APIクライアントのデバッグのような合理的かつ制限された用途にのみ使用されます。 新しいAPIのバージョンで動作するもの。このようなバージョン管理されたAPIは期間限定であるべきで、限られたAPI利用者グループにのみ提供されるべきである（例えばクローズドベータ期間中）。そうでなければ、コミットしてはいけないところでコミットしてしまうことになります。

APIバージョンに有効期限がある場合のメンテナンスについて、いくつか考えてみました。ウェブサービスの実装によく使われるすべてのプログラミングプラットフォーム/言語（Java, .NET, PHP, Perl, Railsなど）では、ウェブサービスのエンドポイント（複数可）をベースURIに簡単にバインドすることができます。こうすることで、簡単に 集める、残す ファイル/クラス/メソッドのコレクション 異なるAPIバージョン間で分離 .

API利用者の立場からすると、特定のAPIバージョンが明らかであれば、開発中という限られた期間だけであれば、それを利用したりバインドしたりすることも容易になる。

APIメンテナの立場からすると、（ソースコードの）バージョン管理の最小単位であるファイルを主に扱うソース管理システムを使うことで、異なるバージョンのAPIを並行して管理することが容易になる。

しかし、APIのバージョンがURIで明確にわかるという点では、以下のような反対意見もあります。 API の履歴が URI のデザインで見える/見えないようになる そのため、時間の経過とともに変更される可能性がある これはRESTのガイドラインに反しています。そうですね!

この合理的な反論を回避する方法は、バージョンレスなAPIベースURIの下に最新バージョンのAPIを実装することである。この場合、APIクライアントの開発者はどちらかを選ぶことができる。

• 最新のものを使って開発する（アプリケーションを保守することを約束し、APIが変更された場合、その変更によって ひどいデザインのAPIクライアント ).

• 明らかになる）APIの特定のバージョンにバインドされるが、限られた期間のみ

例えば、API v3.0が最新のAPIバージョンだとすると、以下の二つはエイリアス（＝全てのAPIリクエストに対して同じ挙動をする）であるべきだ。

http://shonzilla/api/customers/1234


http://shonzilla/api

/v3.0

/顧客/1234
http://shonzilla/api

/v3

/顧客/1234

さらに、APIクライアントが依然として 古い APIは、最新の旧バージョンを使用するように通知する必要があります。 使用しているAPIのバージョンが古い、またはサポートされていない場合 . そのため、以下のような廃止されたURIにアクセスすることになります。

http://shonzilla/api

/v2.2

/顧客/1234
http://shonzilla/api

/v2.0

/顧客/1234
http://shonzilla/api

/v2

/顧客/1234
http://shonzilla/api

/v1.1

/顧客/1234
http://shonzilla/api

/v1

/顧客/1234

のいずれかを返さなければなりません。 リダイレクトを示す30x HTTPステータスコード と共に使用されるもの Location リソースURIの適切なバージョンにリダイレクトするHTTPヘッダは、このままである。

http://shonzilla/api/customers/1234

API のバージョニングシナリオに適したリダイレクト HTTP ステータスコードは、少なくとも 2 つあります。

• 301 恒久的に移動されました 要求された URI を持つリソースが、別の URI (API バージョン情報を含まないリソースインスタンスのパーマリンクであるべき) に永久に移動したことを示す。このステータスコードは、廃止された/サポートされていないAPIバージョンを示すために使用することができ、APIクライアントに バージョン管理されたリソースURIは、リソースパーマリンクに置き換えられました。 .

• 302が見つかりました は、要求されたリソースが一時的に別の場所にあることを示しますが、要求されたURIはまだサポートされている可能性があります。このステータスコードは、バージョンレスのURIが一時的に利用できないとき、リダイレクトアドレス(例えばAPiバージョンを埋め込んだURIを指す)を使ってリクエストを繰り返すべきで、それを使い続けるようにクライアントに伝えたい(つまりパーマリンク)ときに有用かもしれません。

• その他のシナリオは HTTP 1.1仕様のリダイレクト3xxの章