APIバージョン化方法の長所と短所は何ですか

StackOverflow https://stackoverflow.com/questions/19840482

  •  29-07-2022
  •  | 
  •  

質問

いくつかの例で、APIをバージョンする2つの方法に気づきました。

そのうちの1つはURLでバージョンを使用しています

/api/v1/products

もう1つは、コンテンツタイプのヘッダーとAcceptヘッダーを使用して、データのAPIバージョンをマークしてサーバーに送信します

Content-Type=application/vnd.company.v2+xml

このアプローチの長所と短所は何ですか？各アプローチを使用するユースケースは何ですか？

役に立ちましたか？

解決 2

URL自体にバージョン番号を使用することに慣れています（/v1/）。個人的には、これははるかにクリーンなアプローチだと思います。このようにして、エンドユーザー（または開発者）はHTTPヘッダーを処理する必要がなく、必要に応じてAPIの異なるバージョンにアクセスするためにREST API/Callを単純に変更できます。

さまざまな言語で出ているHTTP APIの一部がHTTPヘッダーを完全にサポートしていない可能性もあると考えているので、常にAPIをエンドユーザーが最も簡単に利用できるようにします。 URLを書き直すことは最も簡単な方法であり、HTTPをサポートするものは何でも動作するはずです。

最後に、URLを使用してAPIバージョンを指定できるようにすることで、Webブラウザーを使用して簡単なテストが可能になります。バージョンをHTTPヘッダーに組み込むと、開発者はプログラミング言語を使用してテストを行うことを余儀なくされます。

他のヒント

両方のメカニズムが有効です。どのパスに従うべきかを知るには、消費者を知る必要があります。一般に、企業や学問的に志向の人々と協力することは、開発者をリソースヘッダーバージョンに向けている傾向があります。ただし、クライアントが小規模なビジネスである場合、URLバージョンのアプローチがより広く使用されています。

ここに私が見つけることができる長所と短所があります（私はそれ以上あると確信しています、そして、いくつかの短所はここで言及されていない回避を持っています）

  1. それはより探索しやすいです。ほとんどのリクエストでは、ブラウザを使用するだけですが、リソースヘッダーの実装では、よりプログラム的なアプローチが必要です。ただし、すべてのHTTPリクエストが調査可能であるわけではないため、たとえば投稿リクエストなど、RESTクライアントプラグインを使用する必要があります。 郵便配達員 また 足. URI Pro/Header Con

  2. URIバージョンのAPIを使用すると、リソース識別とリソースの表現が一緒に装備されています。これは、休息の基本原則に違反しています。 1つのリソースは、1つのエンドポイントのみで識別する必要があります。この点で、リソースヘッダーバージョンの選択の選択は、より学問的に理想的です。 Header Pro/Uri Con.

  3. URIバージョンAPIは、クライアント開発者にとってエラーが発生しやすく、馴染みのあるものです。 URLによるバージョン化により、開発者は一目でサービスのバージョンを把握できます。 fクライアント開発者は、ヘッダーにリソースバージョンを含めることを忘れている場合、最新バージョン（バージョンをインクリメントするときにエラーを引き起こす可能性がある）または301（永久に移動）エラーに向けられるかどうかを決定する必要があります。いずれにせよ、初心者のクライアント開発者にはさらに混乱があります。 URI Pro/Header Con
  4. URIバージョンは、同じアプリケーションで複数のバージョンをホージングすることに役立ちます。この場合、フレームワークをさらに開発する必要はありません。注：これを行うと、ディレクトリ構造には、V2ディレクトリにかなりの量の重複コードが含まれている可能性が高いです。また、更新を展開するにはシステムの再起動が必要です。したがって、この手法は可能であれば避ける必要があります。 URI Pro/Header Con.
  5. HTTPヘッダーにバージョンを追加して、既存のプロジェクトでは、その開始からバージョン化をまだ念頭に置いていませんでした。 Header Pro/Uri Con.
  6. による RMMレベル3休憩の原則：HyperMedia Controls, 、HTTP Acceptとコンテンツタイプのヘッダーを使用して、データのバージョン化とデータの説明を処理する必要があります。 Header Pro/Uri Con.
  7. バージョンをURLに配置すると、クライアントはコードの変更を調整する必要があります（または、SMART、構成の場合）、新しいAPIにバージョンを調整する必要があります。 Header Pro/Uri Con.

さらに読みたい場合は、ここに役立つリンクがあります。

URLでバージョンを使用する方が良いです。私はしばらく前にこれを探していました、そして、議論する次の2つのリソースに出会いました 安らかなAPIデザイン 長々と。

  1. 実用的な安らかなAPIを設計するためのベストプラクティス - ヘッダー経由ではなく、URL経由のバージョン。
  2. programmers.stackexchange.com : 予見された変化の計画計画のための推奨パターンは何ですか？

TL; DR回答: ：URLでバージョン＃を使用することが推奨されるアプローチです。

私が出会った中で最もウェル設計されたAPIのいくつか - Instagram API と stackoverflow.com API - どちらもこのアプローチをAPIバージョン化に使用します。

ライセンス： CC-BY-SA と 帰属
所属していません StackOverflow
scroll top