web-dev-qa-db-ja.com

バージョン管理REST API。各APIには独自のバージョンがあります

URLでREST APIsのバージョンを指定することは非常に一般的です。具体的には、パスの先頭で、つまり次のようなものです。

POST /api/v1/accounts
GET /api/v1/accounts/details

ただし、バージョンが各APIに関連付けられているデザインは見たことがありません。つまり、各APIのバージョンを個別に維持します。例：

POST /api/accounts/v2
GET /api/accounts/details/v3

このアプローチを使用して、重大な変更が必要な場合に特定のAPIのAPIバージョンを増分します。API全体のバージョンを増分する必要はありません。

一般的なスタイルの代わりにこのスタイルを使用することの欠点は何ですか？

restapi-designversioningenterprise-architectureengineering
15
Eng.Fouad

あなたが呼ぶものsingleREST APIは、REST API's特定のリソースのセットまたはresources。REST APIの機能。あらゆる種類のソフトウェアなど、パッケージ全体が単一の機能やリソースではなくバージョン/更新されます。

あなたの質問は、REST APIパッケージのリソースがモジュール式であり、個別に開発およびバージョン管理される可能性があるという状況で意味をなすでしょう。

次に、私が見る限り、提案されたリソースロケータの命名規則の主な短所は次のとおりです。

  • APIユーザーの場合、リソースロケータがはるかに複雑になり、予測可能性が低く、記憶しにくく、安定性が低くなります。
  • モジュール開発者の場合、their ownリソースロケータ。
  • 複数のモジュールが更新されているため、上記の短所が指数関数的である限り、リソースロケーターの変更ははるかに頻繁になります...

APIを作成するときの主な目的の1つは、使いやすくすることです...

互換性のない変更を導入したり、REST APIにHTTPヘッダーを使用したりすることもできます。

HTTPヘッダーアプローチの詳細については、以下の他の回答を参照してください。 https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/

13
ClemC

さらに良い方法は次のとおりです。 コンテンツネゴシエーション を使用して、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ヘッダーに基づいてリクエストの転送先を選択するプロキシを、サービスの異なるバージョンの前に置くことができます。

これにより、同じエンドポイント上で（異なるバージョンだけでなく）異なるsemanticsを持つ新しいフォーマットをサポートすることもできます。たとえば、アカウントのlistを/api/accountsにPOSTすると、バッチが作成され、別のAPIエンドポイントを構築する必要がなくなります。それ。

12
Jack

重要なことは、各エンドポイントを個別にバージョン管理する場合、各エンドポイントを個別にデプロイできる必要があるということです。

すべてのエンドポイントが同じコードベースにあり、依存関係を共有して一緒にデプロイされるため、APIは通常1つのバージョンを持っています。

「ああ、私の変更が影響を及ぼさないことは確かです」という理由で変更を加えたときにバージョンを更新していないと、間違いを犯したときに問題が発生します。

さらに、APIのv1とv2の両方を同時にデプロイする必要があります。これは通常、各バージョンを個別のサーバーにデプロイし、それに応じてトラフィックをルーティングすることで行われます。

単一のAPIバージョンがない場合、これははるかに複雑になります。

5
Ewan