53

API バージョニングのベスト プラクティスを見てみましたか? 、しかし答えに確信が持てないので、より具体的な例でバージョン管理の部分をもう一度質問します。私は 2 つの URI を持っています (1 つは URI の一部としてバージョン管理があり、もう 1 つはバージョン管理なし):

http://xxxx/v1/user/123    -> favored solution in discussed thread
http://xxxx/user/123

最初のリンクが REST の考え方を表しているかどうか疑問に思っています。http://xxxx/v1/user/123いつかのようなより高いAPIバージョンがあることを示唆しているので、私は混乱していhttp://xxxx/v2/user/123ます。しかし、これは REST 用語では意味がありません。API バージョン自体は HTTP 1.0 または 1.1 であり、HTTP 要求内で既に送信されています。この REST リソース中心のビューは、SOAP や Java インターフェースなどの他の API インターフェースとは大きく異なります (修飾名で API バージョンを使用するのが一般的です)。

REST でバージョニングが意味を持つ唯一のことは、そのリソースの表現です (たとえば、新しいフィールドが追加または削除されます)。このバージョニングは、次のようなコンテンツ ネゴシエーションの部分に属します。

http://xxx/user/123 + HTTP 'Accept' Header -> Content negotation through header
http://xxx/user/123?v=1                    -> for perma-links/hyperlinks

このようなバージョンのコンテンツ ネゴシエーションは、パス内の URI の一部である可能性があると主張することもできますが、同じリソースに対して異なる URI を使用することになり、ある時点でリダイレクトを維持する必要があるため、直観に反すると思います。

要約すると、REST URI には API のバージョン管理はなく、リソースの表現のバージョン管理のみが行われます。表現 version-info は content-negotiation に属します (queryParam または HTTP 'Accept' として)。

どう思いますか？どの点に反対/同意しますか?

4

8 に答える 8

38

同意します; URIはアイデンティティを表します。新しいバージョンが導入されてもアイデンティティは変わりません。もちろん、追加の概念のための新しいURIがあるかもしれませんし、既存のURIはリダイレクトするかもしれません…しかし、URIに「v2」を含めることは私にはRPCishのにおいがします。

これはRESTとは何の関係もないことに注意してください。実際、RESTの観点からは、すべて文字にすぎません。

于 2010-01-08T15:27:15.163 に答える
11

HTTP 要求ヘッダーをリッスンできます。X-API-Versionヘッダーが存在する場合、サーバーはそのバージョンの API を使用する必要があります。ヘッダーが存在しない場合、サーバーは最新バージョンの API を使用する可能性があります。

> GET /user/123 HTTP/1.1
> Host: xxx
> X-API-Version: >=1.5.1, <2.0.0
> Accept: application/json
>

< HTTP/1.1 200 OK
< X-API-Version: 1.6.12
<
< { "user": { "id": 123, "name": "Bob Smith" } }
<
于 2010-01-08T15:42:36.497 に答える
9

それだけの価値はありますが、マヌエルに同意します。私の推論は、この質問How to version REST URIsで見ることができます。

賛否両論ある人も多いと思いますが、私は気にしません。ハイパーテキストの制約を尊重している限り、URL が実際にどのように見えるかは、クライアントに大きな影響を与えません。

于 2010-01-08T03:29:05.703 に答える
2

APIで提示されるリソースのURIにバージョンが表示されないようにすることに同意します。それは彼らを「かっこいい」ものにしません。また、変更される可能性が最も高いのは表現であることに同意します。

ただし、特定の表現の内容を変更するとどうなるかという問題が発生します。たとえば、フロブニッツの元のJSON表現が

{"x": "bam", "y": "hello"}

「z」フィールドを追加したい場合は、クライアントが、ある種のデータスキームのバージョン2を使用していることをある程度認識している必要があると感じるかもしれません。

それについてはよくわかりません。私はあなたがいくつかのオプションを持っていると思います：

  • 穏やかに変化する表現に直面して、クライアントを柔軟にします。上記の例では、まだJSONディクショナリを生成しています。
  • 必要に応じて、表現自体にバージョンを配置します（この例ではバージョンフィールド）。そうすることで、JSONコンテンツタイプ内でサブ表現を効果的に宣言することになります。しかし、それはかなり制限されていると思います。
  • 独自のMIMEタイプを使用し、それらをバージョン管理します：application / x-my-special-json1.0、application/x-my-special-json1.1。これにより、表現を互いに独立してバージョン管理できます。繰り返しになりますが、これを使用すると、何が起こっているのかを知るようにクライアントに大きな要求をすることになります。

一般に、自分で発明していないクライアントのAPIと表現を最適化する必要があると思います。他の人があなたのリソースを発見したときに作成するもの。これは、システムをより堅牢にするのに役立つ便利な設計制約が組み込まれているため、プライベートなものを作成する場合でも役立つと思います。

于 2010-01-12T11:29:16.813 に答える
1

別のアプローチは、「1 つの表現に複数の API がある」ということです。

http://xxx/user/123/api/1.json

必要に応じて、次のようにリクエストするときに最新の API を使用して表現を返すことができます。

http://xxx/user/123.json

個人的には他のソリューションの方が好きですが、これはまだここで提案されていない別のアプローチです。

于 2010-08-11T12:52:21.433 に答える
1

http://xxxx/v1/user/123は、いつかhttp://xxxx/v2/user/123のような 上位の API バージョンが存在することを示唆しているため、混乱を招きます。

それは示唆していませんが、あなたは将来その能力を持っています.

しかし、これは REST 用語では意味がありません。API バージョン自体は HTTP 1.0 または 1.1 であり、HTTP 要求内で既に送信されています。

YOUR API のバージョンと、リクエストを行うために使用している HTTP のバージョンは同じである必要はありません。

このようなバージョンのコンテンツ ネゴシエーションは、パス内の URI の一部である可能性があると主張することもできますが、同じリソースに対して異なる URI を使用することになり、ある時点でリダイレクトを維持する必要があるため、直観に反すると思います。

あなたが示したように、バージョンを URI パラメータとして使用しても問題ありません。

http://xxx/user/123?v=1 -> パーマリンク/ハイパーリンク用

于 2010-01-08T01:33:55.500 に答える
0

REST の場合、ほとんどの回答が忘れているのはデータ要素です。複数のバージョンの API がまだ同じデータ層を共有していると思います。これは、データ レイヤーによって、下位互換性のある方法で考える必要があることを意味します。行わなければならない大きな変更は、API が下位互換性のある方法で変更された場合にのみ可能です。実際には、これは、API ドキュメントで日付による非推奨を使用して何かがいつ削除されるかを示しながら、追加のプロパティがエンティティにサイレントに追加されることを意味します。理想的には、API キー ユーザーのメール アドレスで登録スキームを使用して、特定の範囲内 (Facebook 風) で非推奨について通知できるようにします。したがって、どこにもバージョンを指定する必要はないと思います。

于 2014-07-16T17:53:47.207 に答える