202 Accepted - API Craft

The old Google Groups will be going away soon, but your browser is incompatible with the new version.
Message from discussion 202 Accepted
Received-SPF: neutral (google.com: 74.125.82.182 is neither permitted nor denied by best guess record for domain of b...@nocarrier.co.uk) client-ip=74.125.82.182;
From: Ben Longden <b...@nocarrier.co.uk>
Content-Type: multipart/alternative; boundary="Apple-Mail=_76CB1EAD-881F-44E7-9291-AC5D704640FC"
Subject: 202 Accepted
Message-Id: <7C7CDC71-0ABB-4245-8E2E-B8D973F5D...@nocarrier.co.uk>
Date: Sun, 4 Nov 2012 15:39:34 +0000
To: "api-craft@googlegroups.com" <api-craft@googlegroups.com>
Mime-Version: 1.0 (Mac OS X Mail 6.2 \(1499\))


--Apple-Mail=_76CB1EAD-881F-44E7-9291-AC5D704640FC
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain;
	charset=us-ascii

Hi all,

I'm currently writing a blog post about a feature of an API I have been =
working on for the past few months. In true 'writing a blog post about =
it' fashion, it's forced me to reconsider some of the decisions that I =
have made - so before I actually publish it I wanted to get some opinion =
from your collective brains.. :-)

The scenario is this. Creating a new resource in my API has the =
potential to take a long time. Usually it's fairly quick, however =
sometimes it takes just too long to wait for the process to complete so =
I return a 202, and a link (via the Location header) to tell the client =
that the resource has not been created - but it has been accepted by the =
server. The link  represents that status of the request.

The point I am reconsidering is what happens when the client issues a =
GET to the resource that represents the status of the request. If the =
request is still pending, I return a 200 (with a cache control header to =
prevent the client from re-checking within the next 5 seconds). The =
content of the response is the same as what the resource *would* be had =
it been created - the fact that it's under a status URL indicates it's =
'pending' state. This could (should?) be a 202 response again to =
indicate that the request is still in an 'accepted' state.

Once the resource has been created, the status resource will return a =
201 (created) or a 404 (gone), so indicate success or failure of the =
creation of the object. It occurred to me that a 201 is an unusual =
response to a GET, however I don't see anything written to say that you =
should not do this...

A 201 would return the location of the resource (url) in the Location =
header, and the response body is the same as what could be found by =
issuing a GET against the new URL (I originally had this as an embedded =
resource because the resource is different). It occurred to me that =
returning the Location header *and* the representation of the resource =
would mean I could also send a cache header so that a secondary GET =
against the resource was not requires in order to populate the cache - =
though in RFC2616 I can only find reference to setting an ETag for the =
new resource on a 201. What are your thoughts on cache headers on a 201, =
and what would intermediaries like varnish make of it?

Of course, most of the above is all hanging off the fact that returning =
a 201 and location headers is not a crazy thing to do on a GET request - =
but from where I am sitting I don't see anything wrong with it.

Thanks,

Ben.



--Apple-Mail=_76CB1EAD-881F-44E7-9291-AC5D704640FC
Content-Transfer-Encoding: quoted-printable
Content-Type: text/html;
	charset=us-ascii

<html><head><meta http-equiv=3D"Content-Type" content=3D"text/html =
charset=3Dus-ascii"></head><body style=3D"word-wrap: break-word; =
-webkit-nbsp-mode: space; -webkit-line-break: after-white-space; ">Hi =
all,<div><br></div><div>I'm currently writing a blog post about a =
feature of an API I have been working on for the past few months. In =
true 'writing a blog post about it' fashion, it's forced me to =
reconsider some of the decisions that I have made - so before I actually =
publish it I wanted to get some opinion from your collective brains.. =
:-)</div><div><br></div><div>The scenario is this. Creating a new =
resource in my API has the potential to take a long time. Usually it's =
fairly quick, however sometimes it takes just too long to wait for the =
process to complete so I return a 202, and a link (via the Location =
header) to tell the client that the resource has not been created - but =
it has been accepted by the server. The link &nbsp;represents that =
status of the request.</div><div><br></div><div>The point I am =
reconsidering is what happens when the client issues a GET to the =
resource that represents the status of the request. If the request is =
still pending, I return a 200 (with a cache control header to prevent =
the client from re-checking within the next 5 seconds). The content of =
the response is the same as what the resource *would* be had it been =
created - the fact that it's under a status URL indicates it's 'pending' =
state. This could (should?) be a 202 response again to indicate that the =
request is still in an 'accepted' state.</div><div><br></div><div>Once =
the resource has been created, the status resource will return a 201 =
(created) or a 404 (gone), so indicate success or failure of the =
creation of the object. It occurred to me that a 201 is an unusual =
response to a GET, however I don't see anything written to say that you =
should not do this...</div><div><br></div><div>A 201 would return the =
location of the resource (url) in the Location header, and the response =
body is the same as what could be found by issuing a GET against the new =
URL (I originally had this as an embedded resource because the resource =
is different). It occurred to me that returning the Location header =
*and* the representation of the resource would mean I could also send a =
cache header so that a secondary GET against the resource was not =
requires in order to populate the cache - though in RFC2616 I can only =
find reference to setting an ETag for the new resource on a 201. What =
are your thoughts on cache headers on a 201, and what would =
intermediaries like varnish make of it?</div><div><br></div><div>Of =
course, most of the above is all hanging off the fact that returning a =
201 and location headers is not a crazy thing to do on a GET request - =
but from where I am sitting I don't see anything wrong with =
it.</div><div><br></div><div>Thanks,</div><div><br></div><div>Ben.</div><d=
iv><div><span class=3D"Apple-style-span" style=3D"border-collapse: =
separate; color: rgb(0, 0, 0); font-family: Helvetica; font-style: =
normal; font-variant: normal; font-weight: normal; letter-spacing: =
normal; line-height: normal; orphans: 2; text-align: -webkit-auto; =
text-indent: 0px; text-transform: none; white-space: normal; widows: 2; =
word-spacing: 0px; border-spacing: 0px; =
-webkit-text-decorations-in-effect: none; -webkit-text-size-adjust: =
auto; -webkit-text-stroke-width: 0px; font-size: medium; "><div =
style=3D"word-wrap: break-word; -webkit-nbsp-mode: space; =
-webkit-line-break: after-white-space; "><div style=3D"margin: 0px; =
font-style: normal; font-variant: normal; font-weight: normal; =
font-size: 18px; line-height: normal; font-family: 'Arial Black'; color: =
rgb(170, 170, 170); "><div style=3D"margin: 0px; font-size: 11px; =
font-family: Helvetica; "><br></div></div></div></span>
</div>

<br></div></body></html>=

--Apple-Mail=_76CB1EAD-881F-44E7-9291-AC5D704640FC--
Create a group - Google Groups - Google Home - Terms of Service - Privacy Policy
Account Options
