Home/ Questions/Q 8943513
In Process

The Archive Base Latest Questions

Editorial Team
  • 0
Asked: 2026-06-15T11:47:23+00:00

I’m trying to understand RESTful Web Services page 274 section HTTP PUT . Issuing

  • 0

I’m trying to understand RESTful Web Services page 274 section HTTP PUT. Issuing PUT against a non-existent resource creates the resource. If PUT causes an existing resource to move, HTTP 301 (Moved Permanently) is returned with the new location. Requests to the old URI return HTTP 301, 404 or 410.

My question is about returning HTTP 301. This seems to imply that resources retain ownership of old URIs forever.

Consider: /companies/{companyName}/departments/{departmentName}

I see the following benefits of using HTTP 301:

  • Concurrency: 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. HTTP 301 allows us to seamlessly redirect the second user to the new URI.
  • Bookmarks: 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.

I see the following problems with HTTP 301:

  • Blocks long-term resource evolution: Over its life-time, department A is renamed to B, C and D. A few years later someone would like to create department A and is prevented from doing so by D. To be fair, I can’t think of any practical example where this would happen so maybe it’s a non-issue.
  • API versions limit its use: Even root resources change over time as new API versions are released and old versions are removed. What’s the point of returning HTTP 301 if the client can’t access the new resource the same way as it could the old?

What is the appropriate course of action? Should the URL hierarchy be modeled differently? Should the behavior/response be different?

Share

Leave an answer

You must login to add an answer.

Need An Account,

1 Answer

  1. Editorial Team

    Answering my own question:

    1. I can’t think of any practical example where keeping HTTP 301 forever would cause problems.
    2. Links are not meant to survive across API versions. Resources from one version should not reference resources from another version (even using HTTP 301). If a resource’s URI changes as the result of an API change, the old API should keep on using the old URI forever.

    UPDATE: According to Willy Tarreau idempotency only requires the application to redirect for a short period of time. Once the client has finished retrying a request, the redirect is no longer needed (at least not for idempotency). You might want to keep redirects around for a longer period of time, to support features such as permalinks, but nothing in the specification forces you to.

    • 0