REST APIのバージョン管理 - 一般的なAPIの

Question

RESTのバージョン管理に関する情報を収集しようとしています。私がフォーラムをチェックするとき、はと見え、Acceptヘッダーを使用するように見えます。 しかし、私がStackExchange、Google、Twitter、Yahoo、Instagram、eBayのAPIをチェックすると、それらはすべてURIを通じてバージョン管理を使用します。

HTTPヘッダーでこの方法を使用する理由がわかりません。私は意見ではなく、事実を知りたい。誰もこれで助けることができますか？

Answer 1

実際には、RESTでAPIのバージョン管理を行う「正しい」方法はありません。それを行うには異なる「間違った」方法を説明する私が読んだ最高の記事はトロイハントすることで、このいずれかになります。

1. URL：記事を引用するYour API versioning is wrong, which is why I decided to do it 3 different wrong ways

   、彼は3つのオプションについて書いています：あなたは、単に例えば、URLにAPIのバージョンを打つ：https://haveibeenpwned.com/api/v2/breachedaccount/foo

2. カスタムリクエストヘッダを：あなたは以前のようにそのようなapi-version: 2
3. としてヘッダを追加し、同じURLを使用してヘッダーを受け入れる：あなたは受け入れるヘッダーを変更したバージョンを指定します例えば、コメントや議論で

、さらにいくつかの技術が同定される：

1. ホスト名：例えばhttps://v2.api.hostname.com/resource
2. クエリ文字列：受け入れヘッダのhttps://api.hostname.com/resource?api-version=2.0
3. バリアント：application/vnd.haveibeenpwned+json; version=2.0

あなたは書きました：

を私は事実ではなく、意見を知りたいのです。

残念ながら、ここには事実はありません。上記のすべての理由で、決定は担当者の意見に基づいています。

私は多くの大きなサービスがURIアプローチに収束していると信じています。これは簡単な実用的な理由の1つです。

初心者のクライアント開発者にとって理解して実装するのが最も簡単です。

これらのサービスは、可能な限りほとんどサポートを必要とせずに、多くのクライアント開発者がAPIとやりとりすることを可能な限り簡単にしたいと考えています。このサービスのAPIとやりとりすることを望みます。

ほとんどのクライアント言語では、文字列を操作してURIを構築するのは非常に簡単ですが、多くの初心者の開発者は受け入れ可能なヘッダーを聞いたことがないでしょう。だから、あなたはそれが開発者の最も低い共通の分母に合うように設計されていると考えることができます。