Subject: Filling out 202 Accepted

From: Mark Nottingham <[email-masked]>
Date: Thu, 11 Aug 2011 14:40:06 +1000

The 202 Accepted status code has come up from time to time, with people liking the idea behind it, but needing a bit more.

<http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-15#section-8.2.3>

I'm wondering if we can clarify things a little bit by adding two bits of text:

--8<---
A 202 response MAY carry a Retry-After header field that indicates an estimation of when the processing might be complete.

It MAY also carry a Location header that indicates the URI of a resource that will be created once processing has completed.
--->8---

Thoughts?

--
Mark Nottingham   http://www.mnot.net/

---

From: Julian Reschke <[email-masked]>
Date: Thu, 25 Aug 2011 10:13:09 +0200

> It MAY also carry a Location header that indicates the URI of a resource that will be created once processing has completed.

Nit: do not use MAY here, just state that the header fields are applicable.

Other than that - the current description says:

"The 202 response is intentionally non-committal. Its purpose is to 
allow a server to accept a request for some other process (perhaps a 
batch-oriented process that is only run once per day) without requiring 
that the user agent's connection to the server persist until the process 
is completed. The representation 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."

...so a "status monitor" resource would also be a candidate for the 
Location header field.

Maybe this is premature? Does anybody use this right now?

Best regards, Julian

---

From: Alexandre Morgaut <[email-masked]>
Date: Thu, 25 Aug 2011 11:20:31 +0200

On 25 août 2011, at 10:13, Julian Reschke wrote:

Best regards, Julian

I use it and here some other APIs using the 202 status code:

SQLShare: http://escience.washington.edu/what-we-do/sqlshare-rest-api
Readability: http://www.readability.com/publishers/api
Pusher: http://pusher.com/docs/rest_api
Blue Box DNS API: https://boxpanel.bluebox.net/public/the_vault/index.php/DNS_API
Signal Spam: https://www.signal-spam.fr/nouveau/doc/plugin-api.pdf
Kasabi: http://beta.kasabi.com/doc/api/update
SoundCloud: http://developers.soundcloud.com/docs/api/me-connections
...

Alexandre Morgaut
Product Manager
Email : [email-masked]<mailto:[email-masked]>
Web :   www.4D.com<http://www.4D.com>

4D SAS
60, rue d'Alsace
92110 Clichy - France
Standard :      +33 1 40 87 92 00

---

From: Mark Nottingham <[email-masked]>
Date: Fri, 26 Aug 2011 10:35:33 +1000

> Nit: do not use MAY here, just state that the header fields are applicable.

Agreed.

> "The 202 response is intentionally non-committal. Its purpose is to allow a server to accept a request for some other process (perhaps a batch-oriented process that is only run once per day) without requiring that the user agent's connection to the server persist until the process is completed. The representation 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."
> 
> ...so a "status monitor" resource would also be a candidate for the Location header field.

If it could be either, I think that would be bad for interop; you wouldn't be sure what following the location would result in. 

> Maybe this is premature? Does anybody use this right now?

I've seen a number of people ask for it explicitly, and I don't think we're getting too far in front by just mentioning what can already occur.

Cheers,

---

From: Julian Reschke <[email-masked]>
Date: Fri, 26 Aug 2011 09:48:33 +0200

> If it could be either, I think that would be bad for interop; you wouldn't be sure what following the location would result in.

Right. I'm just not sure which of these makes more sense, so before 
picking one we probably should look at existing usage.

Best regards, Julian

---

From: Mark Nottingham <[email-masked]>
Date: Fri, 26 Aug 2011 18:03:02 +1000

On 26/08/2011, at 5:48 PM, Julian Reschke wrote:

> Right. I'm just not sure which of these makes more sense, so before picking one we probably should look at existing usage.

My thinking was that Location has a defined semantic in a 201, and arguably 202 should follow the same pattern.

---

From: Julian Reschke <[email-masked]>
Date: Fri, 26 Aug 2011 13:47:19 +0200

> My thinking was that Location has a defined semantic in a 201, and arguably 202 should follow the same pattern.

Yes, if it makes sense and matches what people do :-)

I had a look at the first entry from Alexandre's list:

   http://escience.washington.edu/what-we-do/sqlshare-rest-api

...and it does something interesting.

The initial 202 comes with a Location header field; the identified 
resource acts both as monitor and final result (202 -> you need to poll 
again, 200 -> here's your result).

I currently do not have time to check the other examples, but we really 
should before putting something into the spec...

Best regards, Julian