RESTful design: Should renamed resources block old URIs forever? [closed] - rest

Question

Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
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?

Answer 1

If PUT causes an existing resource to move, HTTP 301 is returned with the new location.
Technically, you can't move resources in HTTP. If you are manipulating resources as a client, what you are doing is:
GET /oldurl
PUT /newurl
DELETE /oldurl
The server will not know that the new URL is a new location for the resource at the old URL, and there is no concept of URL persistence through redirection which can be established by the client using universal HTTP methods. If the service provides an API which allows you to move items, for example by passing certain parameters, and essentially doing the above behind the scenes but also creating a redirect in the process, then it is up to the service as to whether that redirect is overwritable with a new PUT operation or not, as well as what kind of redirect is to be used.
It's my understanding that when a post title gets renamed, we're supposed to keep track of the old name and return HTTP 301 when a client references the old address.
This has nothing to do with REST and is a manifestation of Cool URIs don't change. In a RESTful service, it is sufficient to link to the new URL via a resource or sequence of resources reachable from your service's entry point.
e.g. a HTML website is the normative example of a REST implementation
service entry point = /blog
/blog links to /blog/archive
/blog/archive links to /blog/new-post-title
since the blog service is designed to be consumed by humans using a web browser, it is expected that they may want to bookmark a URL to revisit it later. This is what redirects are for.
a machine-to-machine API has to do something similar:
service entry point = /
/ links to /companies with a rel of "http://myservice/rels/companies"
/companies links to /companies/new-company-name with a rel of "item"
No mention needs to be made of the old company name, because machines are not expected to bookmark a location, but instead to begin navigating from the entry point each time.

Answer 2

I would return a simple 404. This signifies that there is nothing matching the requested uri, and from the documentation, specifies:
No indication is given of whether the condition is temporary or permanent.
This way it is perfectly valid to created new resourced to replace those that existed sometime in the past.
Otherwise, if you're going to move a resource by renaming it, you could always return a 302, specifying the resource resides at a different location. You could return this status until a replacement is generated. The user must continue to use these headers to make sure the resource is still relocated:
Since the redirection might be altered on occasion, the client SHOULD continue to use the Request-URI for future requests.

Answer 3

Answering my own question:
I can't think of any practical example where keeping HTTP 301 forever would cause problems.
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.