HTTP response code when resource creation POST fails due to existing matching resource

Question

Imagine we have an API where a new Employee can be created through a POST to

www.example.com/api/employees

An employee could be described as,

{
  name: "John Smith",
  tax_number: "ABC123"
}

The tax number is universally unique for all humans. If a create were made, and a record already existed in which the name and tax number matched an existing record, it is safe to assume the requester would like a reference to that record returned (with it's internal id and other data the client may not have, eg. created at, updated at).

What would the HTTP status code be for returning that resource? I suppose a redirect could be used with a return of just the id, but I'd prefer to enclose the entire object in the response.

This case is unique to a simple duplicate error, in the sense that if a duplication is attempted it means the record you wish to create already exists- as opposed to it conflicting with an existing record.

Solution 1

I think if you Post a resource to an API, you expect a code 201 that will state that the resource was created, and the body will (can) contain the resource. Otherwise you first have to check if the resource is already created, but this will need two calls.

otherwise, you have the status code 409 :

The request could not be completed due to a conflict with the current state of the resource.

[Edit] after reading on Restfull Web Apis from amundsen, Ruby and Richardson

Best would be to use the 409 status code that states that there is a conflict with a resource that exists on the server. Put the url of that "conflicted" resource in the Location Header of the response and add a message of the conflict in the body

Solution 2

There is a 409 Conflict response code, that is commonly used to let the client know such entity already exists on the server. It might not be very intuitive to have to parse the body of an error response but if you specify this in your API documentation there shouldn't be a problem (to put the info about the original entry in the response body).

Comments

[metacubed]

From the HTTP/1.1 spec: "This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request.". I think that does not really fit this situation.

[Cedric Dumont]

but here he tries to create a resource with a tax_number that is the same as another resource already created in the backend. so the message could return that there is a conflict with another resource already created and returning the already created resource in the body. But this could also be done with a 403 status code forbidden having the same error message.

[metacubed]

Right, but for a 409, how can the consumer resolve the conflict? They can't very well go and change the person's tax number, can they? :D Really, nothing can be done except show an error to the user with the failure reason.

[Cedric Dumont]

the 409 states there is a conflict and in the returning body, he can have the conflicted resource. But if 409 is not acceptable, then I would go for 403 forbidden instead of 500, as for me 500 status code states a problem with the code, or unhandle exceptions or other internal defect

[nrjohnstone]

I think in this case to resolve the 409, the client application would need to display a message that the existing tax number already exists and would they like to update the existing resource instead. Resolving the conflict does not mean you need to try the same method again, in this case, if the user wants to edit, GET the latest copy of the tax number and then PUT the changes

[JWAspin]

@metacubed The complete statement is: "The response body should include enough information for the user to recognize the source of the conflict. Ideally, the response entity would include enough information for the user or user agent to fix the problem; however, that might not be possible and is not required." (webdav.org/specs/rfc2616.html#status.409) So 409 is still valid in this case.