title: Design philosophy and best practies of a restful api
body: <p>I'm have the fortunate option to redesign our main project public api. 
  What started as a goal to make a restful api, have [after a lot of extra added features] ended up as a rest/json-rpc mismatch.</p>
  
  <p>So, time to rethink and redesign. However I need some ideas on how to solve some more complex operations.</p>
  
  <p>The basic <a href="http://en.wikipedia.org/wiki/Create,_read,_update_and_delete" rel="nofollow">CURD</a> operations are implemented already and works fine.</p>
  
  <p>Each resource is accessed by hierarchical slugs:</p>
  
  <pre><code>GET /project/fubar/fishes
  </code></pre>
  
  <p>There are also locale and output formatting added:</p>
  
  <pre><code>GET /project/fubar/fishes.en-us.json
  </code></pre>
  
  <p>Ok, now to the tricky part:</p>
  
  <p>The basic resource in the project have the similarity to a folder with a title and sub-nodes . A "folder" can have sub-folders and items.</p>
  
  <p>What would be the best practice to add a new folder or an item to a folder?</p>
  
  <p>PUT/PATCH is needed to update the information about the folder, not to link resources to it?
  POST is needed to create a new folder.</p>
  
  <pre><code>POST /project/fubar/fishes
  </code></pre>
  
  <p>And to add a bit more, what would be best practice to distinguish the folder to folder and item to folder link operations. Bear in mind that the link can and will have another name then the target. Similar to a symlinks in POSIX systems.</p>
  
  <p>My idea is (to an existing resource):</p>
  
  <pre><code>POST /project/fubar/fishes
  {
     link: /project/fubar/dogs
     title: DOGS!
     type: folder
  }
  </code></pre>
  
  <p>And how about the other way around; unlink?</p>
  
  <pre><code>DELETE /project/fubar/fishes/dogs
  </code></pre>
  
  <p>But is this a good design or will it come back to me later?</p>