API バージョン管理のベストプラクティスは? [closed] 質問する

これは良い質問ですが、難しい質問です。URI設計のトピックは、REST API の最も重要な部分であると同時に、その API のユーザーに対する潜在的に長期的な取り組みでもあります。

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

一方、APIを通じて消費されるすべてのリソースとその側面を予測することは難しいという現実もあります。幸いなことに、API全体を設計する必要はありません。黙示録すべてのリソース エンドポイントと、すべてのリソースおよびリソース インスタンスのアドレス指定スキームを正しく定義すれば十分です。

時間が経つにつれて、特定のリソースごとに新しいリソースや新しい属性を追加する必要が生じる可能性がありますが、リソースのアドレス指定スキームが公開されて最終的なものになった後は、API ユーザーが特定のリソースにアクセスするために使用する方法は変更しないでください。

このメソッドは、HTTP 動詞のセマンティクス (例: PUT は常に更新/置換) と、以前の API バージョンでサポートされている HTTP ステータス コード (人間の介入なしに動作していた API クライアントが引き続きそのように動作できるように、引き続き動作する必要がある) に適用されます。

さらに、APIバージョンをURIに埋め込むと、アプリケーション状態のエンジンとしてのハイパーメディア(Roy T. Fieldings 博士論文で述べられている) リソース アドレス/URI は時間の経過とともに変化するため、API バージョンはリソース URI に長期間保持すべきではなく、つまりAPI ユーザーが依存できるリソース URI はパーマリンクであるべきという結論に達しました。

確かに、ベース URI に API バージョンを埋め込むことは可能ですが、新しい API バージョンで動作するAPI クライアントのデバッグなど、合理的かつ制限された用途に限られます。このようなバージョン管理された API は、時間制限があり、限られたグループの API ユーザー (クローズド ベータ期間中など) のみが利用できるようにする必要があります。そうしないと、コミットすべきでない場所にコミットすることになります。

有効期限が設定されている API バージョンのメンテナンスに関するいくつかの考察。Web サービスの実装に一般的に使用されるすべてのプログラミング プラットフォーム/言語 (Java、.NET、PHP、Perl、Rails など) では、Web サービスのエンドポイントをベース URI に簡単にバインドできます。この方法により、異なる API バージョン間でファイル/クラス/メソッドのコレクションを個別に収集して保持することが簡単になります。

API ユーザーの視点から見ると、特定の API バージョンがこれほど明白であれば、限られた時間、つまり開発中のみであれば、そのバージョンを操作してバインドすることも簡単になります。

API メンテナーの観点から見ると、主にファイルを (ソース コード) バージョン管理の最小単位として扱うソース コントロール システムを使用すると、さまざまな API バージョンを並行して管理する方が簡単です。

ただし、API バージョンが URI で明確に表示されることには注意点があります。API履歴が URI 設計で表示/非表示になるため 、時間の経過とともに変更される傾向があり、REST のガイドラインに反するため、このアプローチに反対する人もいるかもしれません。私も同感です。

この合理的な反対意見を回避する方法は、バージョンレス API ベース URI で最新の API バージョンを実装することです。この場合、API クライアント開発者は次のいずれかを選択できます。

• 最新のバージョンを使用して開発します (設計が不十分な API クライアントを壊す可能性のある API の変更からアプリケーションを保護するために、アプリケーションを維持することを約束します)。

• 特定のバージョンのAPIにバインドする（これは明らかですが）が、限られた時間のみ

たとえば、API v3.0 が最新の API バージョンである場合、次の 2 つはエイリアスである必要があります (つまり、すべての API リクエストに対して同じように動作します)。

http://shonzilla/api/customers/1234 
http://shonzilla/api /v3.0 /customers/1234
http://shonzilla/api /v3 /customers/1234

http://shonzilla/api /v2.2 /customers/1234
http://shonzilla/api /v2.0 /customers/1234
http://shonzilla/api /v2 /customers/1234
http://shonzilla/api /v1.1 /customers/1234
http://shonzilla/api /v1 /customers/1234

http://shonzilla/api/customers/1234