CODEWITHSUNDEEP
resthttp-headershttp-status-codes
matsev
matsev

Reputation: 33779

HTTP Status 202 - how to provide information about async request completion?

What is the appropriate way of giving an estimate for request completion when the server returns a 202 - Accepted status code for asynchronous requests?

From the HTTP spec (italics added by me):

202 Accepted

The request has been accepted for processing, but the processing has not been completed. [...]

The entity returned with this response SHOULD include an indication of the request's current status and either a pointer to a status monitor or some estimate of when the user can expect the request to be fulfilled.

Here are some of thoughts:

Upvotes: 38

Views: 38489

Answers (3)

matsev
matsev

Reputation: 33779

Although not explicitly mentioned specifically for the 202 - Accepted response code, the Retry-After header seems to be a suitable option. From the documentation:

The Retry-After response-header field can be used [...] to indicate how long the service is expected to be unavailable to the requesting client.

Upvotes: 6

Remy Lebeau
Remy Lebeau

Reputation: 597215

You can use the Location header to specify the URL of the status monitor. Things like current status and estimate can either go in custom headers (which noone but your own software would use), or in the response body (which a web browser would display to a user, at least).

Upvotes: 16

Jon
Jon

Reputation: 437584

Definitely do not abuse existing HTTP headers for this. Since it's your own server, you get to define what the response looks like. You can (and should) pick whatever response works best for the intended recipient of this information and return the actual information in the response body.

For example, if you are only interested in displaying a human-readable message then you could return text/plain saying "Your request is likely to be processed in the next 30 minutes.".

At the other end of the spectrum, you might want to go all the REST way and return application/json, perhaps formatted like this (I totally made this up on the spot):

{
  "status": "pending",
  "completion": {
    "estimate": "Thu Sep 08 2011 12:00:00 GMT-0400",
    "rejected-after": "Fri Sep 09 2011 12:00:00 GMT-0400",
  },
  "tracking": {
    "url": "http://server/status?id=myUniqueId"
  }
}

Upvotes: 24

Related Questions