Pulp

If I change the name of a Pulp 3 repository, then the URI to that repository changes. Though I haven't checked, there's a reasonable chance that this behaviour is also true for other types of resources too.

This is bad! Why? Because cool URIs don't change. Say it with me: Cool URIs don't change. There's a couple good reasons for URIs to be immutable.

One of the biggest benefits of RESTful HTTP APIs is that they're cache-friendly. (If you're not aiming for a high degree of cache-ability, then why are you even trying to make a RESTful HTTP API? Just make an RPC HTTP API, or something else.) When a resource is changed with an HTTP PUT, PATCH, or POST, then that resource isn't supposed to move. It's merely been updated. Caches count on this. If an HTTP PUT, PATCH or POST changes the URI of a resource, then caches can't do their job. A cache that tries really hard to do its job might break a client, and a client that works around caches with cache-busting headers will quickly drown the backing application.

There's other issues, too. For example, how can a client deterministically differentiate resources? For example, let's say that one client asks Pulp to asynchronously rename repository "bar" to "biz" and repository "foo" to "bar," and a second client asks for repository "bar" to be published. Which repository is published? There's absolutely no way to know. Mutable URIs are a recipe for race conditions!

"But that's a multi-user example, Jeremy! We're only serving single-client use cases."

Sure. That's unfortunate. But let's think about how this might affect a single client. Let's say that a client wants to rename repository "foo" to "bar" and "bar" to "foo." In what order should the client do this? It can't, at least not without using a temporary name. Let's hope that that other name isn't already used. This introduces unnecessary complexity and fragility into all clients. And what happens if any of these operations are done in the wrong order, or if the server (which is presumably multi-threaded) does things in a different order? The application breaks.

A single client might have many objects in-memory at a given time, and therefore several references to a repository. Imagine that a repository is renamed. How can all of these objects be updated? Can they all just issue an HTTP GET request to the href that they have? Nope. They'll get information about the wrong repository, or a 404. The client has no good way to update its state. Let's hope that the client doesn't do anything wild like cache information on disk for re-use between sessions. one of the big benefits of RESTful HTTP APIs is that they're stateless. Mutable URIs break statelessness.

One of the other big benefits of a RESTful HTTP API is that it promotes client-server decoupling. A good RESTful API gives opaque, fully-built URIs to clients. Client's don't need to construct URIs - they just ask for them. This makes client logic considerably simpler. A client that has to construct URIs by interpolating keys into a templated URI is much more complex. It needs to know which pieces of information that a server application provides might be used as keys, where those keys need to be placed into a URI, and the fact that when a property of a resource changes, existing cached URIs might become out of date and need to be re-built. And as discussed in the previous paragraph, there's already no good way to do this. So now clients need to do the nigh-impossible task of updating in-memory or on-disk objects whose URI might have changed, aaaand they need to perform URI templating with possibly out-of-date information. Why in the world should clients be forced to eat this complexity?