What status code should be returned if the POST completes successfully but does not lead to the creation of anything new?

Question

We have an endpoint that, when sent, creates a new version of the resource and returns 201 and the location of the newly created resource. It determines the new version number based on a comparison of the current version and the version that you are sending (using a set of rules like semver).

If the published version is identical to the existing version, the version number is not updated. What should we return in this case?

• We could just return 201, although we have not technically created anything.
• I do not want to return 409, because this is not a conflict, for example, when you send a message with the same identifier. If you posted the same thing when the existing version was a little different, you would gladly have received 201.
• We could just return 200, but then it would seem strange and increase the response codes that users with

Is idempotency response 201?

Any best deals?

Answer 1

How about 303 - see others? It seems to fit. I draw your attention to this proposal
from the specification https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

This method exists primarily to allow the output POST-activated script to redirect the user agent to the selected resource.

It is like what you want to do with me. Here is the rest.

10.3.4 303 See Others

The response to the request can be found under a different URI and MUST be retrieved using the GET method on this resource. This method exists, first of all, in order for the output of the activated POST script to redirect the user agent to the selected resource. The new URI is not a replacement for the link to the originally requested resource. Response 303 MUST NOT be cached, but the response to the second (redirected) request may be cached.

The URI must specify a different URI. If the request method was not HEAD, the response object SHOULD contain a short hypertext note with a hyperlink to the new URI (s).

Note: Many pre-HTTP/1.1 user agents do not understand the 303 status. When interoperability with such clients is a concern, the 302 status code may be used instead, since most user agents react to a 302 response as described here for 303 

Answer 2

I am a little puzzled by the other answers, as some of them are almost right. So, let a little clarify the situation. If all requests are actually executed using the POST method, in the context of ReSTfulness, they must modify the state on the target server. Otherwise, the POST value is a little relaxed, as you can see in RFC 7231, p. 4.3.3 .

Since the purpose of the requests is to create a new version of the resource, they failed if a version with this presentation already exists. This will disqualify any 2xx class response codes. From section 6.3 :

The 2xx code class (successful) indicates that the client request was successfully accepted, understood, and accepted.

If you absolutely wanted this, you could go for 202 / Accepted , which is "intentionally evasive." This is a bit stretched since this status code is meant to be processed in a queue. I would advise doing this.

The 204 / No Content code suggested by others is a bit of a bad choice. This was absolutely correct if you POST ed to the resource you were updating.

As a result, there is neither an informational (1xx), nor a server error (5xx). Let's look at the 3xx class first. From section 6.4 :

The 3xx status class (redirect) status indicates that the user agent must take additional steps to complete the request.

One of the most famous here will be 304 / Not Modified . Although this code seems to fit perfectly, this code, unfortunately, is not applicable here. It can only be returned in response to conditional GET or HEAD requests.

302 / Found might seem like the next one. However, this code is for temporary redirects, which is most likely not what you need.

As suggested here, 303 / See Other is a really good choice:

The status code 303 (see another) indicates that the server redirects the user agent to another resource [...], which is designed to provide an indirect response to the original request. [...] This status code applies to any HTTP method. It is mainly used to allow the output of a POST action to redirect a user agent to a selected resource.

All other 3xx codes deal with various forms of redirects that are unlikely to be related to the situation here.

Final view, status code 4xx. From RFC 7231, sec. 6.5 :

The 4xx error code class (Client Error) indicates that the client seems to be mistaken. Unless it responds to a HEAD request, the server MUST send a view containing an explanation of the error situation, and whether this is a temporary or permanent condition. These status codes apply to any request method.

Very few of them are really divided into the request body. Two of those who did this stand out here: “ 400 / Bad Request , which is too wide in design. It is - if you want - a solution for everyone. However, this will mean that the request body is incorrectly distorted (as in syntactically incorrect), which probably not so.

More interesting is 409 / Conflict . From the RFC (focus):

Status code 409 (conflict) indicates that the request cannot be completed due to a conflict with the current state of the target resource .

The definition wording puts this code in accordance with the PUT method, but is no exception. Repeat the 4xx code definition:

These status codes apply to any request method.

422 / Unprocessable Entity is a contender, but implies a semantic error, which is actually not the case here.

Ultimately (the drumroll), the last piece of the puzzle can be found in section 4.3.3 :

If the result of the POST processing is equivalent to representing an existing resource, the source server MAY redirect the user agent to this resource by sending a 303 response (see the "Other" section) with the existing resource identifier in the "Location" field.

Pay attention to "MAY". So you can choose between 303 and 409. I think 409 is better suited, since a clearly earlier request presented a state that is incompatible with the current one. OTOH, 303 may be a political way to go closer to the standard. In any case, as a consumer of your API, I would really like to know if my requests have worked. And be it without any effect.

Answer 3

If nothing was created by the operation, 201 not suitable for this:

6.3.2. 201 Created

Status code 201 (Created) indicates that the request is complete and resulted in the creation of one or more new resources. [...]

Below are some parameters that could be considered if the operation completes successfully:

6.3.1. 200 OK

A status code of 200 (OK) indicates that the request succeeded. The payload sent in response 200 depends on the request method. For the methods defined by this specification, the estimated value of the payload can be summarized as:

[...]

• POST : presentation of the status or results received from the action;

[...]

In addition to the CONNECT responses, the 200 response always has a payload, although the source server MAY generate a zero-length payload body. If no payload is required, the source server should send 204 (no content). [...]

6.3.5. 204 No content

Status code 204 (no content) indicates that the server has successfully completed the request and that there is no additional content to send the response payload to the body. [...]

If the operation failed:

6.5.1. 400 Bad Request

A status code 400 (failed request) indicates that the server cannot process the request because it is perceived as a client error (for example, the syntax of an invalid request, incorrect generation of request messages, or routing of a fraudulent request).

11.2. 422 Unprocessable Entity

Status code 422 (raw entity) means that the server understands the content type of the request object (therefore, the status code 415 (Unsupported Media Type) is inappropriate), and the syntax of the request object is correct (thus, status code 400 (Bad Request) is inappropriate) but could not process the contained instructions. For example, this error condition may occur if the body of the XML request contains well-formed (i.e., syntactically correct) but semantically erroneous XML instructions.

Answer 4

I do not think that for this case the idempotency problem is a problem, since the state of the system is not the same as in the case of the internal query, because the entity now exists, so you can answer with different code.

200 should be fine, but it's a little strange, as you said.

I never used this, but I read that in some cases you need to redirect from 302 in order to access another resource, in which case I think it is applicable, return 302 and make a link to the old semver, assuming that you have an endpoint for this object.

Answer 5

If the POST'd resource has the same version number but different data, then 409 is appropriate. But if the data is the same as already saved, then 409 may not be required. Through the troubleshooting process, I would say 200 OK would be ok.

We could just return 200, but then it would seem strange and increase the response codes that users with

If this is a costly issue, consider fixing 201 , not 200 . The fact is that for any sufficiently complex service at some point there may be a situation where a 20X (where X is not 0) is applicable. So this means that we encode each of the responses 20X and check the time if our services have situations when 20X preferable to 200 ? I suspect not. Therefore, if there is a specific reason for answering with 20X , for example, to work with a specific use case, just use 200 and reduce the amount of coding and documentation required. I suspect that for most scenarios, the calling client does not care.

Answer 6

Ultimately, the correct answer probably depends on which client uses your API. If you build a client too, you can do whatever you prefer ... (Just not too crazy.)

---

Assuming you are writing an API and a client :

My opinion / suggestion ...

• If there is an IS version number: 201 HTTP status code will match.
• If there is NOT the new version number: 200 or 204 HTTP status code will match well.
• If the client does not know that the version number has changed or the same: Send 200 HTTP status code.

If you are not in control of the client consuming your API: Obviously, rely on what they expect.

---

You can also view all HTTP status codes in the HTTP RFC specification. The above status codes also refer directly to the corresponding section.

Answer 7

A 201 Created should be used whenever you create a new resource without any doubt.

As defined in the HTTP RFC Method Definitions , either 200 Ok or 204 No Content is the appropriate response if the operation does not create a new resource depending on the contents of the response body.

An action performed by the POST method may not result in a resource that can be identified using a URI. In this case, either 200 (OK) or 204 (No content) - the corresponding response status, depending on whether or not the response includes an object that describes the result.

If the resource was created on the source server, the response SHOULD be 201 (Created) and contain an object that describes the status of the request and refers to the new resource, as well as the location (see section 14.30).

Now, returning to your original question about what to use when the operation is successful and there is nothing to return, you should use 204 No Content . This status code is specifically designed for scenarios where the requested operation completed successfully, but there is no additional relevant information that the server can provide.

Status code 204 (no content) indicates that the server has successfully completed the request and that there is no additional content to send the response payload to the body.

Answer 8

201 : when creating a new version

202 : when upgrading an existing version

204 : when the request is accepted, but processing is not performed

by def, 204 = No content

The server has completed the request, but it does not need to return the entity-body and may want to return updated meta-information. The answer MAY include new or updated meta-information in the form of entity-headers, which, if they MUST be associated with the requested option.

If the client is a user agent, he SHOULD NOT change the look of his document from what caused the request to be sent. This answer is primarily intended to allow the entry of actions without causing a change in the active viewing of the agent document, although any new or updated meta information MUST be applied to the document in the currently active user agent mode.

Answer 204 MUST NOT include the body of the message and therefore always ends with the first empty line after the header fields.

So, its a little touch to your needs, but I think it suits best.