Use http status 202 for asynchronous operations

Question

I am writing a REST API for a service that will accept user contributed data. I would like to keep all operations completely asynchronous, this includes PUT, POST, DELETE an

Answer 1

This is a really old question, but I would like to offer up a slightly different view of this, which I do not claim to be correct, just my view.

From the client perspective

Let's start off with the initial HTTP request. First and foremost, the request should be POST. You are sending a message to the server to create a resource. GET and PUT are not valid in this case because:

• A GET is not valid in this context because a GET is meant to obtain the resource at a specific location
• A PUT is not valid because you are not creating the request, you are asking the server to create the request.

From the service perspective

So now you are sending a POST to the server to process a request. The server has really 3 possible return values (not including the 4xx and 5xx errors):

• "201 Created" indicates that the service got the request and was able to process it immediately, or within an acceptable time period. This time period is completely up to the service design. It is up to the service developer to define this.
• "202 Accepted" indicates that the service got the request and is processing it. This is used when the service knows something is going to take a while. The other perspective is that if the service is reliant on any other asynchronous operation that it has no way of determining the outcome, then it should return the "202 Accepted" response. Finally, some service designers may simply always return "202 Accepted" regardless of how quickly it can be done.
• In some cases, you would get a "302 Found". This is usually when the service can identify a request as generating a resource that already exist (and is still valid and not in an error state) and that reusing an existing resource is acceptable. Not all services work like this: posting a comment to a thread should always create a new resources. Other services do: post a set of criteria to get a list of doctors produces the same list of doctors. If this information can be reused, then reuse it.
• With all these responses, the "Location" HTTP Header is returned to the client containing where the resource can be found. This is important and where some people tend to diverge in approach, as you will see later. If the resource can be reused with other requests, the "Location" should really be generated in a way that the same requests always generate the same URLs. This provides for a good deal of caching and reuse.

When the service has completed the request successfully, it will create the resource at the location that was returned to the client.

Now this is where I start seeing things a little different from the response above.

If the service fails to complete the request, it should still create a resource at the location that was returned to the client. This resource should indicate the reason for the failure. It much more flexible to have a resource provide failure information than trying to shoe-horn it into the HTTP protocol.

If the service gets the request for this resource before it is completed, it should return a "404 Not Found". The reason I believe that it should be a "404 Not Found" is because it really does not exist. The HTTP specifications do not say that "404 Not Found" can only be used for when a resource is never going to exist, just that it doesn't exist there now. This type of response to an asynchronous polling flow is completely correct in my opinion.

There is also the scenario of when a resource is supposed to only be there for a fixed time. For example, it may be data based on a source that is refreshed nightly. What should happen in these cases is that the resource should be removed, but an indicator should be provided to the service that it can know to return a "410 Gone" status code. This basically is telling the client that the resource was here, but is no longer available (ie: may have expired). The typical action from the client would be to resubmit the request.

From the client perspective again

When the client gets the response for it's initial POST, it gets the "Location" and makes the request to the service using that URL using a GET (again, not POST). The service will generally response with these values:

• "200 OK" indicates that the request did complete. The result of the request is returned in the content body, providing the content in the format defined by the Accept HTTP header.
• "404 Not Found" would tell the client that the request did not complete yet, the resource is not there yet, and, in this case, it should basically try again later.
• "410 Gone" would be returned in cases where the client may attempt to get the resource after a long period of time and it's not there anymore. In this case, it should simply resubmit the original query

The one thing that needs to be pointed out is that the resource that is returned is generally in a format that can define success and failure responses. The client should be able to determine from this resource if there was an error, what it was, and be able to respond accordingly.

Also, the service developer may make it so that service expires and deletes the error resource after a short period of time.

So that's my thoughts on this question. It's very late to the party, but hopefully future readers may see a slightly different view to a commonly asked question.