We have an orderShare resource whose attributes include an order number and a customer number. Both must be specified in the POST request to create the resource. However, there can only exist one orderShare per unique order number and customer number combo.
Currently I return an error if someone attempts to create an orderShare for a customer number and order number when such a resource already exists.
An alternative solution is to return the existing resource. I’m not sure whether that violates the spec (formally or in spirit). For example, it seems weird to return 201 Created and a Location header when returning an existing resource. Another complication is that the POST request can specify other fields which do not match the existing resource - one must decide whether they should be set to the requested values or kept as-is.
I happen to have a very similar scenario where two different people can create the (shared) resource. If it happens that one created the resource right before the other tries, I plan to both update the existing (shared) resource and give back its’ current form with a 201 Created. The alternate is returning a 409 Conflict but then the client needs to re-ask for that existing resource to update it instead. However, realistically I know what to do in this case and can handle it all within the same request on the server.
Hm, just wonder, does your server throw exception in case when you creating new combo client_id-order_id? I’m pretty sure, that you have unique key on those. So IMHO server should send this result to client. That he cannot creates that resource, because resource exists.
POST is always reserved for creation, see:
The POST method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line. It essentially means that POST request-URI should be of a collection URI.
What you are telling in alternative scenario more likely looks like PUT:
RFC-2616 clearly mention that PUT method requests for the enclosed entity be stored under the supplied Request-URI. If the Request-URI refers to an already existing resource – an update operation will happen, otherwise create operation should happen if Request-URI is a valid resource URI (assuming client is allowed to determine resource identifier).
The server could decide that it recognizes the resource that would be created and redirect to it. I use HTTP status code 303 See Other (https://tools.ietf.org/html/rfc7231#section-6.4.4) when that kind of resiliency is needed. The agent would use GET to retrieve the resource at the URL from the Location headers.
