title: REST-ish URI design for multiple dependent resources
body: <p>I'm trying to design a REST-ish based Web Service to interface with a farm animal management system I am working on.</p>
  
  <p>To explain the problem in detail, I have a collection of <strong>animals</strong> belonging to a farm. Each animal has its own information - such as name, ID number, breed age, etc. Therefore, I would assume a URI such as the following would suit:</p>
  
  <pre><code>/animals               &lt;- retrieve list of animals
  /animals/{animal-id}   &lt;- Retrieve only one animal
  /animals?breed=sheep   &lt;- Search/query
  </code></pre>
  
  <p>The problem arises when I try to link in other dependent resources to each animal. An animal <strong>can</strong> have a collection of <em>weight</em> information, as well as what I call <em>comments</em> (observations made for a particular animal). Each of these are dependent and only exist to that one particular animal, but are themselves a resource I want to access.</p>
  
  <p>The easiest approach IMO would be to nest the resources within the animal URI:</p>
  
  <pre><code>/animals/{animal-id}/weights
  /animals/{animal-id}/comments
  </code></pre>
  
  <p>However, I see a need to access and query the <em>weights</em> and <em>comments</em> directly, without referencing the animal. Examples in usage would be to retrieve the most recent (or all) weight(s) from all animals of a particular breed <code>...?breed=sheep</code> or even return weights/comments for a selection of individual animal ID's <code>...?animals={ID1},{ID2},{...}</code>.</p>
  
  <p>Further complications arise when I want to add one comment to multiple animals at once. (please excuse my representation of a POST and JSON)</p>
  
  <pre><code>POST ....
  {
    "comment":"Animal moved to paddock B",
    "animals":[{id1}, {id2}, ...]
  }
  </code></pre>
  
  <p>I understand that the obvious solution to this problem would be to GET and POST (for example) to <strong>each</strong> animal that I wanted to retrieve/edit. I would prefer not to do this though, as eventually I want this service accessed from mobile devices, and therefore decreasing the number of calls seems wise. </p>
  
  <p>I believe that the web standards allow CSV in the URI, so something like this could work,</p>
  
  <pre><code>/animals/{id1},{id2},{..}/weights
  </code></pre>
  
  <p>But, I am expecting cases where ten(s) of animals may need to be referenced at once (or queried), and that would lead to a messy and unfriendly URI.</p>
  
  <p>My current perceived solution is to expose <em>weights</em> and <em>comments</em> as their own resource, which allows me to access and query them directly</p>
  
  <pre><code>/weights
  /weights/{weight-id}
  /weights?breed=sheep
  </code></pre>
  
  <p>and even post directly to the collection</p>
  
  <pre><code>POST /comments
  {
    "comment":"Animal moved to paddock B",
    "animals":[{id1}, {id2}, ...]
  }
  </code></pre>
  
  <p>But what would <code>/animals/{animal-id}/weights</code> return? Is it even needed, or would I just reference a link to the <code>/weights?animal={animal-id}</code> resource itself? But is it okay to link to a queried resource?</p>
  
  <p>Am I making one redundant, or just providing "another" way to access the information?</p>
  
  <p>Is there something that I am doing wrong, am I letting my database influence my service model, or am I just missing the point completely?</p>
  
  <p>I am quite new to this, and have read quite a few contradicting arguments regarding these issues, and so am quite confused as to what is best for my requirements.</p>
  
  <p>Thanks!</p>