title: RESTful design: Should renamed resources block old URIs forever?
body: <p>I'm trying to understand <a href="http://shop.oreilly.com/product/9780596529260.do?sortby=publicationDate" rel="nofollow">RESTful Web Services</a> page 274 section <code>HTTP PUT</code>. Issuing <code>PUT</code> against a non-existent resource creates the resource. If <code>PUT</code> causes an existing resource to move, <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.2" rel="nofollow">HTTP 301 (Moved Permanently)</a> is returned with the new location. Requests to the old URI return HTTP 301, 404 or 410.</p>
  
  <p>My question is about returning <code>HTTP 301</code>. This seems to imply that resources retain ownership of old URIs forever.</p>
  
  <p>Consider: <code>/companies/{companyName}/departments/{departmentName}</code></p>
  
  <p>I see the following benefits of using <code>HTTP 301</code>:</p>
  
  <ul>
  <li><strong>Concurrency</strong>: If one user renames a company while another is in the process of navigating to a department, the latter will get HTTP 404 in spite of the fact that they did nothing wrong. <code>HTTP 301</code> allows us to seamlessly redirect the second user to the new URI.</li>
  <li><strong>Bookmarks</strong>: Both humans and computers need to bookmark URIs for long-term storage. Humans post links in discussion forums. Computers use URIs for caching purposes and user preferences.</li>
  </ul>
  
  <p>I see the following problems with <code>HTTP 301</code>:</p>
  
  <ul>
  <li><strong>Blocks long-term resource evolution</strong>: Over its life-time, department <code>A</code> is renamed to <code>B</code>, <code>C</code> and <code>D</code>. A few years later someone would like to create department <code>A</code> and is prevented from doing so by <code>D</code>. To be fair, I can't think of any practical example where this would happen so maybe it's a non-issue.</li>
  <li><strong>API versions limit its use</strong>: Even root resources change over time as new API versions are released and old versions are removed. What's the point of returning <code>HTTP 301</code> if the client can't access the new resource the same way as it could the old?</li>
  </ul>
  
  <p><strong>What is the appropriate course of action?</strong> Should the URL hierarchy be modeled differently? Should the behavior/response be different?</p>