URLのREST APIのバージョンを指定することは非常に一般的です。具体的には、パスの先頭、つまり次のようなものです。
POST /api/v1/accounts
GET /api/v1/accounts/details
ただし、バージョンが各APIに関連付けられているデザインは見ていません。つまり、各APIのバージョンを個別に管理します。すなわち：
POST /api/accounts/v2
GET /api/accounts/details/v3
このアプローチを使用すると、破壊的な変更が必要なときに特定のAPIのAPIバージョンをインクリメントします。API全体のバージョンをインクリメントする必要はありません。
一般的なスタイルの代わりにこのスタイルを使用することの欠点は何ですか？
回答:
あなたが呼ぶ、単一の REST APIをするREST APIのと呼ばれるかもしれないリソースの特定のセットまたはリソース。また、REST APIの機能として見ることもできます。あらゆる種類のソフトウェアなど、パッケージ全体がバージョン管理/更新されており、単一の機能やリソースではありません。
あなたの質問は、REST APIパッケージのリソースがモジュール式であるため、個別に開発およびバージョン管理される可能性があるコンテキストで意味があります。
そして、私が見る限り、提案されたリソースロケーターの命名規則の主な短所は次のとおりです。
APIを構築する際の主な目的の1つは、使いやすくすることです...
重大な変更を導入したり、HTTPヘッダーを使用してREST APIをバージョン管理したりするためのより良い方法を見つけることができますか？
HTTPヘッダーアプローチの詳細については、以下の他の回答とhttps://www.troyhunt.com/your-api-versioning-is-wrong-which-is/をご覧ください。
さらに優れたアプローチは次のとおりです。コンテンツネゴシエーションを使用して、Content-TypeおよびAcceptヘッダーでAPIをバージョン管理します。
POST /api/accounts
Accept: application/vnd.my-api.account.v1+json
201 Created
Location: /api/accounts/285728
Content-Type: application/vnd.my-api.account.v1+json
{ ... account data here ... }
別のバージョンを取得するには、単に異なるコンテンツタイプのを要求しAcceptます。このように、サーバーがサポートする特定のバージョンは、URL構造から完全に独立しています。同じサーバーは、Acceptヘッダーに基づいて応答するものを選択するだけで、複数のバージョンをサポートできます。または、バージョンごとに異なるデプロイメントを使用したい場合は、Acceptヘッダーに基づいてリクエストを転送するサービスを選択したサービスの異なるバージョンの前にプロキシを配置できます。
また、これにより、同じエンドポイント上で（異なるバージョンだけでなく）異なるセマンティクスを持つ新しい形式をサポートできます。たとえば、アカウントのリストをPOSTする/api/accountsことはバッチ作成を意味する可能性があり、そのために別のAPIエンドポイントを構築する必要はありません。
vnd一部と+構文の目的です：これがベンダー固有の型のサブタイプであることを示すためapplication/json。これがまさにコンテンツタイプの設計対象です。リソースは複数の形式で利用できます。クライアントに、どの形式が必要かを選択するように依頼しています。さらに、APIリクエストが標準のHTTPキャッシングセマンティクスを使用できない理由はありません。
重要なことは、各エンドポイントを個別にバージョン管理する場合、各エンドポイントを個別に展開できる必要があるということです。
通常、APIには1つのバージョンがあります。これは、すべてのエンドポイントが同じコードベースにあり、依存関係が共有され、一緒にデプロイされるためです。
「ああ、私の変更がそれに影響を与えないことを確信している」という理由で、変更を行ったときにバージョンを更新していない場合、間違えたときに問題が発生します。
さらに、v1とv2の両方のAPIを同時にデプロイする必要があります。これは通常、各バージョンを個別のサーバーに展開し、それに応じてトラフィックをルーティングすることにより行われます。
単一のAPIバージョンがない場合、これははるかに複雑になります。