Subject: PUT, side effects and 201 Created?

From: Mark Nottingham <[email-masked]>
Date: Mon, 3 Apr 2006 16:25:47 -0700

2616 specifically allows PUT to have side effects;

> A single resource MAY be identified by many different URIs. For  
> example, an article might have a URI for identifying "the current  
> version" which is separate from the URI identifying each particular  
> version. In this case, a PUT request on a general URI might result  
> in several other URIs being defined by the origin server.
>
> HTTP/1.1 does not define how a PUT method affects the state of an  
> origin server.
and it also says (in the context of PUT)

> If a new resource is created, the origin server MUST inform the  
> user agent via the 201 (Created) response.
So, if I PUT something to /foo, and it has the side effect if  
creating /foo;2006-04-03, is the response required to be a 201 Created?

I.e., read literally, the above requirement requires a 201 Created  
when PUT results in *any* resource being created -- even as a side  
effect.

This is IMO unnecessarily constraining, and should be relaxed; e.g.,  
changed to something like

"If a new resource is created at the Request-URI, the origin server  
MUST inform the user agent via the 201 (Created) response."

--
Mark Nottingham
[email-masked]

---

From: "Mark Baker" <[email-masked]>
Date: Mon, 3 Apr 2006 20:01:39 -0500

> creating /foo;2006-04-03, is the response required to be a 201 Created?

Seems so.

> MUST inform the user agent via the 201 (Created) response."

Hmm, *that* seems more constraining to me; could the server not just
return a Location header with value "/foo;2006-04-03" in the 201?

Mark.
--
Mark Baker.  Ottawa, Ontario, CANADA.       http://www.markbaker.ca

---

From: Mark Nottingham <[email-masked]>
Date: Mon, 3 Apr 2006 18:55:51 -0700

How is it more constraining to allow responses other than 201? This  
effectively forces the server to inform the client of the location of  
*any* resource that happens to be created by a PUT, whether or not  
that is useful or relevant information.

At the end of the day, this isn't really a testable requirement, so  
it's not a big deal; was just wondering what was in people's minds  
when this was written.

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

---

From: "Mark Baker" <[email-masked]>
Date: Mon, 3 Apr 2006 22:53:08 -0400

On 4/3/06, Mark Nottingham <[email-masked]> wrote:
> How is it more constraining to allow responses other than 201?

It's not more constraining along that axis, sure, and in fact I've
always wondered why the requirement wasn't a SHOULD rather than a
MUST... which I think would address your issue.

> This

Can't help you there 8-)

Mark.

---

From: Julian Reschke <[email-masked]>
Date: Tue, 04 Apr 2006 09:14:30 +0200

> return a Location header with value "/foo;2006-04-03" in the 201?

Well, I know of code that uses the status code for a PUT to find out 
whether the server has created a new resource (201) at *that* URL, or 
whether it was just updated (200). That may be considered a bad 
assumption, but I wouldn't be surprised if some generic client start to 
act weird if they think a certain URL was mapped, PUT to it, and then 
get a 201.

Best regards, Julian

---

From: Stefan Eissing <[email-masked]>
Date: Tue, 4 Apr 2006 09:23:24 +0200

Am 04.04.2006 um 01:25 schrieb Mark Nottingham:
> This is IMO unnecessarily constraining, and should be relaxed;  
> e.g., changed to something like
>

I'd file that under clarification. I think you give a clearer  
formulation of what the spec writers did intend to say.

//Stefan

---

From: Stefan Eissing <[email-masked]>
Date: Tue, 4 Apr 2006 10:41:32 +0200

>> creating /foo;2006-04-03, is the response required to be a 201  

Hmm, "side effect" is too general. Look at the two side effects:

Example A: WebDAV DeltaV uses 201 and Location header to indicate the  
upon checking a new version was created and where it lives.

Example B: A general server failure, normally answered with 500, is  
logging the failure reason in a new resource which can be retrieved  
via GET. It makes no sense to answer a 201 instead of 500 in such a  
case.

Clearly we would like to say that A is following the intention of the  
spec, while returning 201 in case B is not required.

Regards, Stefan