Is it appropriate to use PUT for resources when the id is deterministically derived from immutable properties?

Question

I'm working with a RESTful API where a POST operation is used to create a user. A required field, which could be an email or a unique user nickname, is unique across the system. The response to this POST contains a unique id for the user, which is a deterministic hash calculated from this unique field. Therefore, the same unique field will always produce the same id, preserving their one-to-one relationship.

Given this structure, there's an inherent challenge regarding the use of the PUT operation. Traditionally, PUT can replace a resource or create a new one if it doesn't exist. However, in this context, the deterministic and immutable relationship between the id and the unique field seems to complicate the semantics of PUT.

My concerns are:

1. Given the deterministic nature of the id from immutable properties, is it a good design choice to implement a PUT method for such resources?
2. If the semantics of PUT are challenged by this design, are there any best practices or potential pitfalls that I should be aware of?

Answer 1

If I understand correctly, you are planning to have a resource along the lines of:

https://yourdomain.com/user

Which supports a POST operation which will return a new resource maybe like:

https://yourdomain.com/user/somesortofhash

There's nothing particularly unusual or difficult allowing PUT to be used on resources created with POST. You can even restrict the ability for the PUT to create a new resource by failing the operation.

The only requirement of PUT is that it needs to be idempotent meaning that if you call PUT successfully multiple times with the same input, the resulting state of the resource will be the same. This is a useful feature because if you have some sort of e.g.: network failure, you can simply retry the PUT call.

What PUT requires in this case is that the called know the id of the user. It is probably a bad idea to have clients calculating the hash for the id themselves as discussed in the comments. Primarily because it would lock you into the hashing routine. In the future you might want to use a UUID instead or perhaps you need to modify the hashing routine because you have had collisions. It really is best to not expose that detail to the client and I take it that you don't want to do that anyway. This doesn't preclude the use of PUT, however.

I think your question may come down to how does the client get that id? First of all, if you return the URI for the user resource from the POST, that's one way. In some circumstances that might even be enough. It's typical though for a REST API to provide a way to look up such resource URIs based on information that they have.

One thing to consider with PUT is that it has complete replacement semantics. This is simple to use but you can run into issues such as dirty reads/writes if you have multiple clients attempting to modify the same resources at the same time. For this reason PATCH is sometimes used to allow clients to update part of a resource without replacing it entirely.

Answer 2

Three variations of PUT:

1. You accept the representation of the resource provided in the request as is, and keep the URI unchanged. This is the primary interaction that PUT was designed for.

2. You use the information in the request to recalculate the representation of the resource yourself, and keep the URI unchanged. Not quite so easy - we need to be a little bit careful with things like Validation headers, see RFC 9110.

If you need to try to change the URI... that's where the dragons lurk in the hungriest dark.

In the case where you expect clients to be bespoke implementations designed to interface specifically with your API, you probably don't have much of a problem - you tell the client implementers how to identify the new URI to be used, and get on with your life.

But if people are connecting to your API using general purpose components (like a web browser), then communicating the URI change to the client gets a little bit spooky. The closest real thing you have are redirects, but automatic redirection may cross you up (especially since for some redirect messages clients have a bit too much freedom about which message they use).

---

Being concerned here is good, and you should investigate carefully to make sure that you understand the tradeoffs involved, and whether "clever" is really the right answer (in both short and long term).

Answer 3

I would just return a well-described 400 Bad request or 409 Conflict in case the unique field is changed. And/or only accept PATCHes that don't include that field.