title: Proper route pattern for RESTful collections with additional resources
body: <p>I have been doing RESTful APIs for quite a bit (exposing and consuming 3rd parties) and I see two following patterns popping up here and there. Each has pros and cons and neither is "clean" in my opinion.</p>
  
  <p>So the situation is: you have a collection resource (e.g. "assets") and you want to expose some additional resources within a collection (e.g. subresources of the collection itself, not the asset, like aggregated view endpoint or some commands).</p>
  
  <p>Two patterns I see are:</p>
  
  <ol>
  <li><p>People create a RESTful collection resource like <code>/assets/${asset-id}</code> and expose everything else they need like <code>GET /assets/owned</code>, <code>GET /assets/summary</code>, <code>POST /assets/recheck-inventory</code>. This looks neat and concise but introduces a clash between <code>${asset-id}</code> and nouns of sub-resource URLs (e.g. <code>asset12345</code> and <code>summary</code> are in the same place in the URL).</p></li>
  <li><p>Others do <code>/assets/items/${asset-id}</code> and expose everything like <code>GET /assets/owned</code>, <code>GET /assets/summary</code> and so on. This is cleaner from routing perspective and a bit more future-proof, but adds an extra noun in the route, which leads to confusion when people are trying to do <code>POST /assets</code> for example.</p></li>
  </ol>
  
  <p>The "best practice" guidelines I went through thus far avoid the question altogether. I also understand that REST is a convention and not the standard, and there is a universal "it depends" answer. Still, I feel like there got to be a generic recommendation here.</p>
  
  <p>Hence the question is: which of two you would use?</p>
  
  <p>UPDATE: to clarify, let us assume that:</p>
  
  <ul>
  <li><code>/assets/owned</code> contains entities of different types, not assets, so it is not a query and you can GET/POST/DELETE items in it.</li>
  <li><code>/assets/summary</code> is an aggregation document (e.g. report with quantities for example)</li>
  <li><code>/assets/recheck-inventory</code> is a command (i.e. POST only)</li>
  </ul>
  
  <p>Also, we want to stick with REST principles:</p>
  
  <ul>
  <li>route's path shall identify an entity and its state uniquely.</li>
  <li>query parameters alter which elements are returned, but do not change the payload format.</li>
  <li>headers are for protocol-level information and do not change service logic (i.e. presentation, security, caching, etc.)</li>
  </ul>