title: RESTful URL design: public vs private API, hierhachy API design pattern, URI vs URL design?
body: <p>I often get into issue like this, very similar to this <a href="https://stackoverflow.com/questions/7833548/hierarchical-restful-url-design?rq=1">Hierarchical RESTful URL design</a></p>
  
  <p>Supposed the service only offers the user to upload a document.</p>
  
  <pre><code>POST, GET /accounts
  PUT, DELETE /accounts/{name}  or /accounts/{id}
  </code></pre>
  
  <p>Now a document is attached to a specific user, whether it is public or not at all is not of concerned here.</p>
  
  <p>The two ways are    <code>POST /documents vs POST /users/documents</code></p>
  
  <p>Why? Because later when a document resource is created, that document is under the user's control. So I would expect to have </p>
  
  <p><code>GET, PUT, DELETE /users/{name}/documents</code> for getting, changing and deleting a bunk of documents the users own.</p>
  
  <p>I can have <code>GET, PUT, DELETE /users/{name}/documents/{name/id}</code></p>
  
  <p>But the same can be achieved just <code>/documents/{users}/.... or /documents/{id}</code>. And this is similar to how one might organize unix files  (though <code>/users/...</code> is also another way to organize files...) You see, there is also a philosophy[phy of uri vs url design.</p>
  
  <p>Another consideration is whether the API is visible to user or not. If this is simply a backend API, only the developer has access  <code>(backend &lt;- frontend server &lt;- frontend ajax)</code>, then a site user may be happier with <code>/users/{name}/documents/{id/name}</code> while some programmers will dislike this long url if the API is public (like twitter api).</p>
  
  <p>What do people think about these issues?</p>