リソースコレクションにAtomを使用する場合のREST APIのバージョン管理

Question

これは何度も繰り返し議論されていることを知っています。私はこれまでのところどこに行っても最終的なハードルを乗り越えることはできません。

私はアプリケーション用のカスタムREST APIを設計しており、メディアタイプを使用してバージョンを変更したいと決めました。アプリケーション/ vnd.mycompany.resource.v2 + xml。私はこのモデルのプロとコンセプトを理解しており、最も柔軟な体重を計るようです。

次のようにそれゆえ私のGETはなります

=== REQUEST ===> 
GET /workspaces/123/contacts?firstName=Neil&accessID=789264&timestamp=1317611 HTTP/1.1 
Accept: application/vnd.mycompany.contact-v2+xml 

<== RESPONSE === 
HTTP/1.1 200 OK 
Content-Type: application/vnd.mycompany.contact-v2+xml 
<contact> 
    <name>Neil Armstrong</name> 
    <mobile>+61456838435</mobile> 
    <email>neil.armstrong@space.com</email> 
</contact> 

問題は、私は私のリソースのコレクションを表すためのAtomフィードとentrysを使用したいということです。こうすることで、私のリソースやAPI構造に感染していないAtomの検索とページ設定を利用できます。資源の私のコレクションを表現するためにアトムを使用し

=== REQUEST ===> 
GET /workspaces/123/contacts HTTP/1.1 
Accept: application/atom+xml; type=feed; 

<== RESPONSE === 
HTTP/1.1 200 OK 
Content-Type: application/atom+xml; type=feed; 
<feed xmlns="http://www.w3.org/2005/Atom"> 
    <title>Contacts Feed</title> 
    <link rel="self" href="https://api.mycompany.com/workspaces/contacts"/> 
    <updated>2011-11-13T18:30:02Z</updated> 
    ... 
    <entry> 
     <title>Neil Armstrong</title> 
     ... 
     <content type="application/vnd.mycompany.contact-v2+xml"> 
      <contact> 
       <name>Neil Armstrong</name> 
       <mobile>+61456838435</mobile> 
       <email>neil.armstrong@space.com</email> 
      </contact> 
     </content> 
    </entry> 
</feed> 

、私はメディアタイプを使用してバージョンに能力を失う：私は私の要求のためのAtomを使用している場合

は、私の要求の構造は今のように見えます。メディアタイプがAtomエントリの内容の中に隠されるようになりました。

 <content type="application/vnd.mycompany.contact-v2+xml"> 

まだ資源回収管理のためにアトムの力を利用しながら、私のリソースのメディアタイプのバージョンを決定するためのベストプラクティスは何ですか？

私はACCEPTヘッダーにそれを渡すことができると考えています。

Accept: application/atom+xml; type=feed; version=1.0 

しかし、あなたはAtomフィードではなく、リソース自体のバージョン1.0を求めているとして、これは混乱しています...

本当にいただければ幸いですすべてのヘルプ！

Answer 1

問題は、あなたがメディアタイプを誤解しているということです。

メディアタイプは、実際のペイロードのストラクチャに関する情報を提供しますが、ペイロードのセマンティクスは提供しません。 「これはXHTMLのページだとわかっているが、それがブログの投稿かAmazonのものかどうかはわからない」 XHTMLページでは、コンポーネントをペイロードから取り出して面白い質問をする方法を知っていますが、ペイロードの解釈はメディアタイプの一部ではありません。

ロイ・フィールディングの例で言い換えると、10,000ビットの配列を100x100ピクセルのGIFファイルとして送信する例を考えてみましょう。 「誰もが知っている」GIFは写真を送るのに使われていますが、それは本当に簡単です。これは、たいていの場合画像になる構造化バイナリを送信するためのメカニズムです。したがって、10,000ビットの配列（おそらく00とFFのグレースケール画像で表現されます）を送信する場合、一般的なデコーダ（GIF）、圧縮されたGIFなどの利点があります。

しかし、この場合、それは絵ではありません。画像として表示することはできますが、無意味な画像です。この場合、画像シナリオに使用されている古典的な意味は関係ありません。そのメリットはフォーマットの偏在性です。

もう1つの例は、エンジニアがレーダー研究を行っていた年前のことです。そこで、彼は本などで見つけられる航空機の3次元図面を撮り、タブレットを使ってAutoCAD図面にエンコードします。 DWG形式は十分に文書化されており、彼はそれらを読むためのコードを持っていました。彼が望んだのは、特定の航空機からの座標と測定値でした。

最終的に彼は "無意味"なAutoCADファイルをたくさん持っていましたが、その中には何の意味もありませんでした。しかし、実際には、彼らは彼のドメインのために良い情報でいっぱいだった。 DWGファイルはメディアタイプでしたが、これらは「CAD図面」ではありませんでした。 （「自発的な再利用」と言うことができますか？）

media-typeで何かをバージョンアップしても問題ありませんが、メディアタイプが実際に変更されている場合にのみ関係します。あなたが指摘したようにATOMは変更されていないか、少なくともあなたのコントロール下では変更されていません。変更された場合、新しいバージョンをサポートしないことを選択することがあります。しかし、ATOMは情報がどのように表現されているか、情報がどのようにコード化されているか、変化していないために変化していない。情報はうまく変化する可能性があり、実際は常に変化します。すべてのATOMフィードは異なる情報で異なります。 MOSTは類似のセマンティクス（ブログフィード）を持っていますが、多くはそうではありません（シナリオなど）。

しかし、どのようにパースしてATOMフィードから情報を取得するかは変わりません。それがメディアの種類です。情報そのものではなく情報の符号化。

したがって、バージョン管理を検出する場合は、ペイロード内をチェックします。それを調べる。たとえば、請求書番号が（おそらく、XPATHのinvoice/inv_noにある）データのV1に対して、あなたはそれを知っています。請求書がそこにない場合、あなたは何をしていますか？あなたはa）他のよく知られている場所（つまりV2）を見ますか、b）エラーを投げます（「これは何でも、請求書ではありません」）。あなたは何があっても、バージョンが何を言っているのか、メディアの種類が何か、何か他のことが何であれ、何かを得ることができるので、それをしなければならないでしょう。

あなたのペイロードは互換性を失うことなく、互換性を保つことができます。バージョンは、すべての情報を利用するためのものです。あなたがAとBを手に入れたら、CとDも持っていたいと思うのですが、クライアントはより限定された情報で手に入れることができます。クライアントがCとDを見ると、AとBを無視することを知っているでしょう。そのデータは非推奨です。サーバーと同じです。何かがAとBを送信している場合は、CとDを送信した場合より古い処理モデルであることを暗示しています。

rel名 "order"と "order_2"新しい顧客は "order_2"を使用し、代わりにそのリンクに従うことを知っています。

または、ペイロードにバージョン識別子を含めるだけで簡単にチェックできます（特にデザインの初期段階です）。

バージョン管理を管理する方法はたくさんありますが、メディアタイプは実際にはそのメカニズムではありません。だから、これは本当にATOMの "問題"ではありません。それで、それは視点の問題です。

私はこっちAcceptヘッダーに関する別の議論があります：REST API having same object, but light

この（私見）あなたのバージョン管理の問題とは無関係なのが、それが拡張されたメディアタイプの例です。しかし、それはなぜ、どのようにしてほとんどの人々が「バージョン管理」を望むかという私の認識です。このケースは同じものにすることができますが、ほとんどの人は、単に他のポストが主張していたデータ表現ではなく、サービスとバージョン管理を関連づけます。

最後に、クライアントまたはサーバーのいずれかが、バージョン管理されたデータを処理するのに十分な柔軟性を備えているか、そうではありません。彼らは（主に、彼らは結局コンピュータです。決定的な私のヘイニー...）彼らは何を話しましたか。 「わからないものを無視する」という単純なルールは、エンコーディングに関係なく、v1をv2に変更することなく、バージョン管理の面で非常に遠い可能性があります。同様に、「自分が持っているものを処理する」は、柔軟で耐性のあるサーバーのための良い規則です。どちらの場合でも問題が発生した場合は、エラー、ログ、オペレーター、24時間のポケットベルが対象となります。