Async ReST with status polling (and how to eventually receive completed result)

Question

I have a request that is expected to take several hours to complete and I can’t quite figure out the ENTIRE flow. I know this has been discussed several times including here, but nothing I found answers the questions below (convincingly).

What I know:

1. I will do a POST /mysomethings
2. The response will be a 202 Accepted with a Location header which will contain a complete url where status can be found (e.g. https://api.example.com/statuses/somestatusuuid).
3. The client can then poll the statuses url and get a 200 OK response with a response body containing something like { statusId: someid, status: somestatusstring, description: somestatusdescriptionstring }

To keep things simple and focused I am ignoring how authorization will be done for these requsts.

My question:

What do I do once the resource for original request is ready (let’s say this means status="complete").

The best I can think of is one of these:

1. The status response will also include (once status="complete") an additional key such as myresourceId: someuuid and the client can then do GET /mysomethings/someuuid

2. The status response (once resource is ready) will include a Location header with a complete url of the resource (e.g. https://api.example.com/mysomethings/someuuid)

3. A combination of both of above so that I have both the url of the resource and its id

Some additional thoughts:

• IMO it would be inappropriate to return the resource itself in the status request because what’s being requested is a status and not the actual resource.

• I also don’t like the ideas suggested in some places to return 202 for the status until resource is ready and then return 201 Created because the status codes are supposed to convey the status of the request, not of the resource (and definitely not of another resource for which the current request only requests a status of).

Does all this sound right? Any and all comments are welcome.

Answer 1

Although you're discarding the option using the HTTP 202 code, you're pretty much describing the situation that the RFC 2616 specification defines for using the 201/202 pair of HTTP responses.

Instead of returning the HTTP 200 code and working with 404, have the server return HTTP 202 (accepted) and write client code to poll until a HTTP 201 (created) is received with a new resource URI in the Location header (or a timeout period occurs).