REST APIのサブリソース、返すデータは？

Question

我々はcustomersとordersを持っている場合、私はこのデータを取得するための正しいRESTfulな方法を探しています：

{ 
    "customer": { 
    "id": 123, 
    "name": "Jim Bloggs" 
    "orders": [ 
     { 
     "id": 123, 
     "item": "Union Jack Keyring", 
     "qty": 1 
     }, { 
     "id": 987, 
     "item": "London Eye Ticket", 
     "qty": 5 
     } 
    ] 
    } 
} 

1. GET /customers/123/orders
2. GET /customers/123?inc-orders=1

私は最後の部分正しいアム/ URLのフォルダ（クエリ文字列パラメータを除く）は、返されるリソースである必要があります..？

この場合、番号1は注文データのみを返し、顧客データは含まないようにしてください。番号2は顧客123を直接指していますが、クエリ文字列パラメータを使用して返された顧客データ（この場合は注文データを含む）を有効/無効にします。

上記2つの呼び出しのうち、上記のJSONの正しいRESTful呼び出しはどれですか？ ...または秘密の番号3のオプションはありますか？

Answer 1

のようなものを返します

GET /customers/123/orders 

：

後者はこのようなものになるでしょう。

1） GET /customers/12 ただし、必ず注文を含めてください。クライアントが注文を使用したくない状況がありますか？または、オーダーアレイが本当に大きくなることはありますか？もしそうなら、別のオプションが必要かもしれません。そのような彼らの受注へのリンクが含ま可能性があり GET /customers/123

2）、：

{ 
    "customer": { 
    "id": 123, 
    "name": "Jim Bloggs" 
    "orders": { 
     "href": "<link to you orders go here>" 
    } 
    } 
} 

これはあなたのクライアントでは、顧客とその注文を得るために2つのリクエストを作成する必要があります。ただし、この方法については、クリーンページングとオーダーのフィルタリングを簡単に実装することができます。

3） GET /customers/123?fields=orders これは、2番目の方法と似ています。これにより、クライアントはAPIをより効率的に使用できますが、サーバーから戻ってくるフィールドを実際に制限する必要がない限り、このルートには進まません。さもなければ、それはあなたが維持しなければならないあなたのAPIに不必要な複雑さを追加します。

Answer 2

カスタマリソースをプロパティとして受注のコレクションが含まれて

GET /customers/123 

の結果がどうなるかのようなルックスを掲載JSON。代わりに、それらを埋め込むか、それらへのリンクを提供することができます。あなたが、私はRESTfulなと考えることができると思う3つのオプションを持っている

{ 
    "orders": [ 
     { 
     "id": 123, 
     "item": "Union Jack Keyring", 
     "qty": 1 
     }, 
     { 
     "id": 987, 
     "item": "London Eye Ticket", 
     "qty": 5 
     } 
    ] 
} 

Answer 3

私は単純に、このデータを生成し、リソースを指し示すURIにHTTP GETリクエストを実行し、このデータ

を取得するための正しいRESTfulな方法を探しています！

TL; DR

• は、RESTは、URIのデザインを気にしない - しかし、その制約の！
• クライアントは、応答内に含まれる動的に識別されたハイパーリンクを介してサーバーから返された可能なアクションによって状態遷移を実行します。
• クライアントとサーバー全体ではなく（サブ）リソースを埋め込むの好ましいハイパーメディアタイプ
• に交渉することができる唯一の

---

興味を持っている場合ので、クライアントはそれを見ることができ、そのリソースへのリンクを返すことを検討

最初に、URIが一意である限り、RESTは実際にはURIデザインを気にしません。確かに、単純なURIデザインは人間にとっては理解しやすいですが、HTMLと比較すると実際のリンクはより意味のあるテキストの背後に隠れる可能性があります。したがって、人間がリンクを見つけることができる限り重要ではありません。それに対してアクションを実行することができます。次に、あなたの「レスポンス」やAPIがRESTfulだと思われる理由は？ APIをRESTfulに呼び出すには、APIは、constraintsのカップルを尊重する必要があります。これらの制約の中には、流行の有名人の1つ、すなわちアプリケーション状態（HATEOAS）のエンジンとしてのハイパーテキストがあります。

RESTは、毎日使用するWebの一般的な概念です。 Webセッションの非常に一般的なタスクは、クライアントが、多くのリンクやその他のリソースを持つHTML文書をクライアントが要求して、クライアントがさらなるページを要求したり、ビデオをストリーミングしたりすることができるようにすることです。クライアント上でのユーザー操作は、返された情報を使用してさらに進めたり、新しいページを要求したり、サーバーなどに情報を送信したりすることができます。RESTfulアプリケーションでも同様です。これは、単にRESTがHATEOASと定義したものです。 "レスポンス"を見てHATEOAS制約を再確認すると、レスポンスにはリンクが含まれていないことがあります。したがって、クライアントはさらに進むためにドメイン知識が必要です。

JSON自体は、データの全体的な構文を定義するだけであり、プレーンXMLと同様のセマンティクスを持たないため、クライアントの検証に使用できるDTDやスキーマがあります。さらなるセマンティックルールが他の場所で利用可能かどうかを確認してください。 JSON上に構築されるいくつかのハイパーメディアタイプがあり、おそらくf.eのように適しています。 application/hal+json（JSONベースのハイパーメディアタイプの比較はこのblog postにあります）。もちろん、あなたは自分のハイパーメディアタイプを定義する権利がありますが、特定のクライアントはそれを理解できないかもしれません。

f.e. HALを見ると、特定のサブリソースに入れることができる_embedded要素が定義されています。これはあなたの場合に理想的なようです。あなたのデザインによっては、ordersもそれ自身のリソースになる可能性があり、したがってGET /orders/{orderId}経由で到達可能です。サブリソース全体を埋め込む代わりに、その（サブ）リソースへのリンクを含めるだけで、クライアントが関心のある場合にデータを参照できるようにすることもできます。

お客様のデータのみを返送したい場合やその他のデータも含めたい場合は、f.e. （HAL f.e.に基づく）異なるハイパーメディアタイプを両方に対して定義する。一方は顧客データのみを返し、他方は顧客データを返す。これらのタイプは、application/vnd.yourcompanyname.version.customers.hal+jsonまたはapplication/vnd.yourcompanyname.version.customer_orders.hal+jsonのように指定できます。これは、要求に単純なクエリパラメータを追加する場合と比較して開発オーバーヘッドを確実にするためですが、セマンティクスはより明確で、HTTP操作ではなくハイパーメディアタイプ（または表現）のドキュメントオーバーヘッドがあります。

もちろん、1つのビューはそのまま顧客データを返しますが、別のビューでは私があまり関係のないトピックで示したresponseと同様の注文を含む顧客データを返すようなビュー構造を定義することもできます。

Answer 4

リソース（の完全な URLで識別される）は、同じ顧客です。 表現のみが、埋め込み注文の有無にかかわらず異なります。

コンテンツネゴシエーションを使用して、同じリソースの異なる表現を取得します。

要求

GET GET /customers/123/ 
Accept: application/vnd.acme.customer.short+json 

応答

200 OK 
Content-Type: application/vnd.acm.customer.short+json 

{ 
    "customer": { 
    "id": 123, 
    "name": "Jim Bloggs" 
    } 
} 

要求

GET GET /customers/123/ 
Accept: application/vnd.acme.customer.full+json 

応答

200 OK 
Content-Type: application/vnd.acme.customer.full+json 

{ 
    "customer": { 
    "id": 123, 
    "name": "Jim Bloggs" 
    "orders": [ 
     { 
     "id": 123, 
     "item": "Union Jack Keyring", 
     "qty": 1 
     }, { 
     "id": 987, 
     "item": "London Eye Ticket", 
     "qty": 5 
     } 
    ] 
    } 
}