Subject: 202 Accepted, Location, and Retry-After

From: James Snell <[email-masked]>
Date: Mon, 24 Oct 2011 08:54:45 -0700

I notice that the current definition of the 202 Accepted response
still does not provide any consistent means of specifying how exactly
to go about checking the response later on... it says only, the "[t]he
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."... which is fine in some respects but leaves
the mechanism wide open for inconsistent behavior among
implementations.

i am wondering if there is an opportunity to tighten this up a little
bit by tying in the use of the Location and Retry-After response
headers...

Essentially,

a 202 Response with a Location header would indicate that a later GET
on the Location URI would return a resource describing the current
status of the request. If the response also contains a Retry-After
header, it is specifying the minimum time that the client is being
asked to wait to expect the request to be complete. A GET on that URI
before the request is available would itself be expected to return a
202 Response.

thoughts?

- James

---

From: Julian Reschke <[email-masked]>
Date: Mon, 24 Oct 2011 18:01:18 +0200

> before the request is available would itself be expected to return a

See thread starting at 
<http://lists.w3.org/Archives/Public/ietf-http-wg/2011JulSep/0343.html>.

My concern was that there are *two* obvious ways to use Location, (1) 
for the final response, (2) for a status monitor. We should research 
what's in use right now, but haven't done so properly yet.

Best regards, Julian

---

From: James Snell <[email-masked]>
Date: Mon, 24 Oct 2011 09:13:10 -0700

Julian, thank you for the pointer, I had missed that thread entirely.
The distinction between the final response and the status monitor
concern could be addressed through the additional application of the
Content-Location header. Within a 202 Response, the Location URI would
be assumed to point essentially to a status monitor, while the
Content-Location would point to the URI of the final response. If they
happen to point to the same URI, then all is still good... otherwise,
the distinction between the two URIs is clear and things are still
good. Should the Content-Location header be omitted, the server is
being purposefully non-committal and is effectively requiring the
user-agent to issue a request to the Location URI to discovery any
further information about the status of the request and the final
response. Should a GET to the Location URI return a 202 response
indicating that the request is not yet complete, it too can contain
both the Location and Content-Location headers. That would seem to me
to effectively clear up any possible confusion that could arise.

On Mon, Oct 24, 2011 at 9:01 AM, Julian Reschke <[email-masked]> wrote:
> My concern was that there are *two* obvious ways to use Location, (1) for
> the final response, (2) for a status monitor. We should research what's in
> use right now, but haven't done so properly yet.
>
> Best regards, Julian
>
>

---

From: Julian Reschke <[email-masked]>
Date: Mon, 24 Oct 2011 18:24:01 +0200

On 2011-10-24 18:13, James Snell wrote:
 > ...

In which case we'd need to special-case status code 202 within 
<http://greenbytes.de/tech/webdav/draft-ietf-httpbis-p2-semantics-latest.html#identifying.response.associated.with.representation>, 
right?

> ...

Best regards, Julian

---

From: James Snell <[email-masked]>
Date: Mon, 24 Oct 2011 09:41:47 -0700

That would be necessary, yes. A Content-Location in a 202 Response
would necessarily point to the expected final resource and would not
be representative of the 202 responses own payload, which, by
definition of the 202 code is supposed to describe the status of the
request. A description of the relationship between the Location,
Content-Location and Retry-After headers within a 202 response would
also need to be added.

---

From: Julian Reschke <[email-masked]>
Date: Mon, 24 Oct 2011 18:49:37 +0200

> Content-Location and Retry-After headers within a 202 response would

There you go. The fact that we need to introduce a new special-case 
without any backwards compat we need to consider makes me very unhappy.

I believe the right thing to do here is to write all of this down as a 
distinct draft, and leverage link relations to identify one of the two 
related resources (or even both).

Best regards, Julian

---

From: James Snell <[email-masked]>
Date: Mon, 24 Oct 2011 10:24:44 -0700

Ordinarily I would agree but, in this case, I'm not convinced that the
backwards compatibility problem is a significant issue. Specifically,
I have not seen (and did not see anything in the examples linked to
within the other thread) any existing cases of 202 that would conflict
with this approach. Should the Content-Location header be excluded
from the 202 response, it would simply be handled as it is today.
Currently, the use of Content-Location in a 202 is rather undefined
and left wide open to interpretation so there's really no solid
precedent to fall back on or conflict with, it would seem.

On Mon, Oct 24, 2011 at 9:49 AM, Julian Reschke <[email-masked]> wrote:
> There you go. The fact that we need to introduce a new special-case without
> any backwards compat we need to consider makes me very unhappy.
>

---

From: Julian Reschke <[email-masked]>
Date: Mon, 24 Oct 2011 19:34:20 +0200

> precedent to fall back on or conflict with, it would seem.

My concern is not backwards compat, but adding special cases without a 
very good reason for them.

Best regards, Julian

---

From: James Snell <[email-masked]>
Date: Mon, 24 Oct 2011 10:44:47 -0700

Noted. In this case, I think the very good reason becomes obvious in
that taking this approach would provide a consistent model for
handling 202 Accepted responses without the extreme ambiguity that
currently exists. As it stands now, there is no way that a user-agent
can consistently deal with a 202 response without falling thru to
specific application logic every time. At least in cases where the 202
returns both the Location and Retry-After headers, a consistent
behavior can be expected and implemented.

On Mon, Oct 24, 2011 at 10:34 AM, Julian Reschke <[email-masked]> wrote:
> My concern is not backwards compat, but adding special cases without a very
> good reason for them.
>
> Best regards, Julian
>

---

From: "Roy T. Fielding" <[email-masked]>
Date: Mon, 24 Oct 2011 13:00:12 -0700

On Oct 24, 2011, at 9:13 AM, James Snell wrote:

> Content-Location would point to the URI of the final response.

No, that is reversed -- the 202 response might be considered
a status monitor's representation and thus point to itself using
Content-Location.  No change to the spec is required for that
interpretation.

I don't see any need to use Location here, since 303 can be used
to point to the final response as a placeholder.

....Roy

---

From: James Snell <[email-masked]>
Date: Mon, 24 Oct 2011 14:04:12 -0700

Hmm, I may be missing something here then... let me tease it out by
walking through a practical example... if I POST an Atom entry to a
Collection URI.. and the server returns a 202 Accepted rather than a
201 Created... what I would expect to get back as the payload of the
204 is the status monitor's representation or a URL to where I can
retrieve the status monitor's representation... that's all fine.
However, what is left entirely up to applications is how that link to
the status monitor's representation is itself represented. The data
format is entirely arbitrary. The goal of using Location in the 202
would be to provide a consistent way of referencing the status
monitors location rather than relying on arbitrary data formats.
Thinking about it further, you're right in that we could use a 303 to
point to the final response... essentially the flow would be...

  HTTP/1.1 202 Accepted
  Location: http://example.org/other-url
  Retry-After: 123

... (after 123 seconds...)

  GET /other HTTP/1.1
  Host: example.org

... (processing not yet complete)

  HTTP/1.1 202 Accepted
  Location: http://example.org/other-url
  Retry-After: 123

... (retry again after another 123 seconds)

 GET /other HTTP/1.1
 Host: example.org

... (received a redirect to the final response...)

  HTTP/1.1 303 See Other
  Location: http://example.org/final-url

Given this.. yeah, you're absolutely right, there's no need to muck
around with the Content-Location header in the 202 Response if it's
assumed that the Location header in the 202 response always points to
the status monitor, but how would I know that the 303 response is
giving me the location of the final resource rather than redirecting
to an alternative location for the final resource... at some point I'm
going to have to either be able to see a Content-Location header that
I *know* points to the final resource or have a specific response code
that says, Here it is.

Thinking about it further...as an alternative... a Web Link headers
could be used instead of Location... there is currently already a
"monitor" link relation registered within the link rel registry that
could potentially do the trick... although I'd have to review the
definition in rfc5989 to make sure)... it would essentially be,

  HTTP/1.1 202 Accepted
  Link: <http://example.org/other-url>;rel="monitor"

The fundamental flow would be the same without any need whatsoever to
muck around with the spec. Hmm...

- James

---

From: Mark Nottingham <[email-masked]>
Date: Tue, 25 Oct 2011 15:57:10 +1100

I'm -1 on this approach; it doesn't make sense for a Location on a 201 to mean "there's the thing I created" while on a 202 it means "here's a status monitor for this resource."

201 + Location is a well-understood pattern, and the semantics translate well to 202.

Furthermore, Content-Location has very specific semantics on a response; you can't just repurpose them. Use a link relation instead.

Cheers,

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

---

From: James Snell <[email-masked]>
Date: Mon, 24 Oct 2011 22:56:27 -0700

Agreed. The more I've thought about it tonight, the more I'm leaning
towards the use of a Link header.