コレクションでもあるリソースの表現を返すためのベストプラクティス

Question

RESTfulインターフェイスを作成したいとします。そのIDに基づいてfooを使用したいと考えています。新しいものはありません。

• GET /api/foo1foo1の表現（JSONなど）を返します。
• DELETE /api/foo1削除foo1。

など

今私は「foo」がコレクション型のものであることを教えてくれてみましょう。だから私は、「foo」というに「バー」を追加できるようにしたい：

• PUT /api/foo1/bar3はfoo1にbar3を追加します。
• GET /api/foo1/bar3は、foo1という表現を返します。
• DELETE /api/foo1/bar3は、foo1からbar3を削除します。
• DELETE /api/foo1foo1を完全に削除します。

ここで問題は残ります：GET /api/foo1は何ですか？私はこの質問で最初に仮定したように、単にfoo1の表現を返しますか？またはそれは棒のリストを返しますか？または、foo1の表現は、foo1との両方の説明であり、のすべての含まれているバーのリストを返しますか？

それともGET /api/foo1単に私が最初に仮定としてfoo1の表現を返し、foo1内のバーをリストするPROPFIND要求管理（WebDAVで撮影したアプローチ）が必要でしょうか？しかし、一貫性を保つために、他のすべてのリストタイプの機能性をに変更する必要はないでしょうか？GET /api/foo1を使用して内容をリストするRESTfulチュートリアルを何千も矛盾させていますか？

Answer 1

webdavのセマンティクスは、実際にはRESTfulインターフェイスのイディオムとは決して調和しませんでした。

理論的には、GETはリソースの状態の表現を取得し、PROPFINDを使用してコレクションのメンバーを取得する必要があります。

だから、あなたがこれを行う必要があります。

• GET/API/foo1は/ - /のみ
• PROPFIND/API/foo1がfoo1の状態を返します - foo1の

ほとんどのメンバーを返しますフロントエンドの開発者は、ブラウザjsの実装では完全にサポートされていますが、PROPFINDを使用するように指示してしまった場合は、驚いてしまいます。

個人的に私はこれを行うだろう要求はRESTfulなイディオムを使用して作られたが、例えば、私のWebDAV実装

にルーティングされているのWebDAV/JSONゲートウェイを使用：

GET /api/foo1/_PROPFIND?fields=name,fooProp1,fooProp2 

そして、それは

を返します

[ 
{ name : "bar1", fooProp1: "..", fooProp2 : ".."}, 
{ name : "bar2", fooProp1: "..", fooProp2 : ".."} 
] 

このアプローチの利点の1つは、クライアントが返されるjsonプロパティを制御することです。これは、豊富なAPIには多くのプロパティがあるため、ほとんどの場合クライアントはそれらのすべてを必要としないため、これは良いことです。

Answer 2

RESTfull APIでのルートとその操作は、開発者によって完全に設計されています。特定のルートを要求しているときに返すものを決定するのは、GET /api/foo1です。

開発者は、/api/foo1/barを含むすべてのルートを設計する必要があります。特定のルートが何をすべきかについての特別なルールはない。 APIがオープンソースのプロジェクトの場合は、すべてのルートを明確かつ明確に文書化してください。

古い学校の戦略について考えて時間を無駄にしないでください。

Answer 3

熟考した後、RESTfulな観点からの最良の概念的説明は、通常、「物」は「コレクション」と同じではないということです。したがって、WebDAVの世界ではdirectory/はファイルを保持するものと同じであるかもしれませんが、RESTfulな世界では、含まれているファイルに対して別のdirectory/files/サブパスがあるかもしれません。そうすれば、保持するファイルとは別にディレクトリを操作することができます。

バーンを含むファームのRESTful APIについて考えてみましょう。終点farm/api/barns/は、納屋のリストを返します。その1つはfarm/api/barns/bigredbarnです。まあ、私はfarm/api/barns/bigredbarn/を検索すると私に納屋の動物のリストが提供されると思います。これがこの質問を促したものです。

実際、納屋の動物はビッグレッドバーンの唯一の側面です。私が直面しているジレンマが生じないこのアプローチで

• farm/api/barns/bigredbarn/animals/
• farm/api/barns/bigredbarn/vehicles/
• farm/api/barns/bigredbarn/haybales/

：それは車や干し草が含まれる可能性があります。