RESTful API Create - should it return conflict if exist, or be idempotent and return 200 if values are the same?

Question

What title says - if I have an endpoint to create element, but the element already exist, what's the best / common practice? Should I:

• Return conflict based on the fact that an object with the key already exist?
• Or check if the existing object is the same, and if so return 200 instead (or other ok-ish status code)?

Thanks!

Answer 1

There is relevant content in RFC 9110, section 13.1.1

Alternatively, if the request is a state-changing operation that appears to have already been applied to the selected representation, the origin server MAY respond with a 2xx (Successful) status code (i.e., the change requested by the user agent has already succeeded, but the user agent might not be aware of it, perhaps because the prior response was lost or an equivalent change was made by some other user agent).

Allowing an origin server to send a success response when a change request appears to have already been applied is more efficient for many authoring use cases, but comes with some risk

Returning a successful response when the server action was a no-op is fine.

But you certainly aren't required to do that - it's also fine to send an error response to the client indicating that their local view of the world is out of date.

---

"Best" practice, presumably, is to sit down and do the math - what's the cost of each implementation? how frequently does it come up? what are the benefits? How much of the cost is pushed back onto the consumers of the API, and is that consistent with the targets we need to meet to get adoption, and so on.