追加のリソースを持つRESTfulコレクションの適切なルートパターン

Question

私はRESTfulなAPIを（露出し、サードパーティを消費して）かなり行ってきました。私はここに2つのパターンが現れています。それぞれに長所と短所があり、私の意見ではどちらも「きれい」ではありません。

コレクションリソース（「資産」など）があり、コレクション内にいくつかの追加リソースを公開したい場合（集計ビューエンドポイントやいくつかのコマンドのように、アセットではなくコレクション自体のサブリソース）。私が見

2つのパターンがある：

1. 人々は/assets/${asset-id}のようなRESTfulなコレクションのリソースを作成し、それらがGET /assets/owned、GET /assets/summary、POST /assets/recheck-inventoryのように必要な他のすべてを公開します。これはきれいで簡潔に見えますが、${asset-id}とサブリソースURLの名詞（たとえば、asset12345とsummaryはURLの同じ場所にあります）の間に衝突をもたらします。

2. その他は/assets/items/${asset-id}となり、GET /assets/owned,GET /assets/summaryなどのすべてが公開されます。これはルーティングの観点から見ればより洗練されており、将来的にはもう少し証明されていますが、例えば人がPOST /assetsを実行しようとしているときに混乱を招くルートに余分な名詞が追加されます。

「ベストプラクティス」のガイドラインはこれまでのところすべての質問を避けています。また、RESTは標準ではなく規約であり、普遍的な "それに依存する"答えがあることも理解しています。それでも、私はここに一般的な勧告があるように感じる。

したがって、問題は2つのうちどちらを使用するかです。

UPDATE：それは、クエリではなく、あなたがGET/POST /その中の項目を削除することができますので、

• /assets/ownedは、異なる種類の実体ではなく、資産が含まれています。私たちはそれを想定してみましょう、明確にします
• /assets/summaryは、集約文書（例えば、数量をたとえばレポート）
• /assets/recheck-inventoryあるコマンドである（つまり、POSTのみ）

また、我々は、RESTの原則を堅持したい：

• 経路のパスは、エンティティとその状態を一意に識別しなければならない。
• クエリパラメータは、返される要素を変更しますが、ペイロード形式は変更しません。
• ヘッダは、プロトコルレベルの情報のためのものであると私はどちらかこれらのアプローチを好きですが、注意していない

Answer 1

サービス論理（すなわち、プレゼンテーション、セキュリティ、キャッシング、など）を変更しないでください、それRESTはしていませんURI構造をどのように設計するかという制約を置くことで、あなたは何か正しいことをすることができます。どうやらこれらのWebサービスの開発者は、このアプローチが正しいと感じました。

フラットURIがはるかに優れているので、あなたのURIで次のようなことをします。

/assets/items/${asset-id} 
    -> /assets/${asset-id} 
/assets/owned 
    -> /assets/?owned 
    -> /assets/?owned=true 
/assets/summary 
    -> /assets-summary 
    -> /assets/ + "Prefer: return=minimal" 

あなたは prefer header hereについての詳細を見つけることができますが、あなたはそれが二次キャッシュキーにしたい場合は vary headerことによってそれを登録する必要があることを、認識することができ

。