REST: Is HTTP 303 considered harmful for asynchronous operations?

Question

When researching the RESTful API for asynchronous operations, I came across the following design pattern:

POST uri:longOperation returns:

• HTTP 202
• Location: uri: pendingOperation

GET uri:pendingOperation returns:

• If the operation is performed
  • Return a progress report.
• If the operation is completed
  • HTTP 303
  • Location: uri: operationResponse

GET uri:operationResponse

• Asynchronous Operation Response

I find the last step questionable. See what happens if the asynchronous operation completes with an error code that does not make sense for an HTTP GET , such as HTTP 409 ("Conflict") .

• No HTTP 303 required to specify a response related to uri: pendingOperation , not uri: operationResponse ?
• Does HTTP 303 this way is considered harmful? If not, why?
• Is this the best we can do, or is there a better way?

Answer 1

No HTTP 303 required to point to uri: pendingOperation-related response as opposed to uri: operationResponse?

spec does not explicitly say this is required, but I tend to agree with you.

Does HTTP 303 use in this way considered harmful? If not, why?

I think that you lose opportunities by doing 303. Although it is “good” to automatically redirect when this is done, it makes it impossible for you to provide metadata around the results that can be used for reporting, etc. Also, many clients do not automatically follow 303, so the client may need to do the work to follow the 303 Location header.

Is this the best we can do, or is there a better way?

I tend to recommend returning a GET uri:pendingOperation return 200 with the status of the resource always with reference to the output when it is "completed". Something like

In case of incomplete

 { "status" : "PENDING" } 

On error

 { "status" : "COMPLETE" "errors" : [ { "typeId" : "OPERATION_TIMEOUT", "description" : " "The request was unable to complete because the systems are unresponsive". } ] } 

When successful

 { "status" : "COMPLETE" "links" : { "result" : { "href" : "http://api.example.com/finished-resource/1234", } ] }