Subject: [Fwd: I-D ACTION:draft-dusseault-http-patch-09.txt]

From: James M Snell <[email-masked]>
Date: Wed, 22 Aug 2007 16:59:06 -0700

FYI... Updated based on recent discussions.

- James

-------- Original Message --------
A New Internet-Draft is available from the on-line Internet-Drafts
directories.

	Title		: PATCH Method for HTTP
	Author(s)	: J. Snell, L. Dusseault
	Filename	: draft-dusseault-http-patch-09.txt
	Pages		: 15
	Date		: 2007-8-22
	
Several applications extending HTTP require a feature to do partial
   resource modification.  Existing HTTP functionality only allows a
   complete replacement of a document.  This proposal adds a new HTTP
   method, PATCH, to modify an existing HTTP resource.

A URL for this Internet-Draft is:
http://www.ietf.org/internet-drafts/draft-dusseault-http-patch-09.txt

[snip]

---

From: Julian Reschke <[email-masked]>
Date: Tue, 28 Aug 2007 11:26:13 +0200

> http://www.ietf.org/internet-drafts/draft-dusseault-http-patch-09.txt

Hi James,

a few comments:

- I think that using warn codes to provide feedback may be problematic; 
in particular the idea to encode data into the message, which in RFC2616 
is plain text. I think a new response header would be better.

- Finally: "Prefer" IMHO should go separate; in particular there are 
unresolved questions such as how are new Prefer codes registered. IANA?

Best regards, Julian

---

From: Yaron Goland <[email-masked]>
Date: Wed, 29 Aug 2007 17:34:26 -0700

As part of the Web3S effort I need to define the equivalent of "Prefer: content-returned" and 209.

My current intention is to introduce a dedicated HTTP request header called "Web3SGetResponse" whose semantics are the same as content-returned. The reason why I have chosen not to use Prefer is that I am uncomfortable with placing all "safe to ignore" headers in HTTP into a single Prefer header. In other words I can't figure out what kind of 'safe to ignore' header wouldn't end up in Prefer and putting everything into Prefer just doesn't seem right.

I choose the name "Web3SGetResponse" to indicate that I'm not trying to solve the general problem, I'm just solving a specific problem in the context of Web3S. If a more generic solution is agreed upon I would be happy to use it. But my vote in that case would be not to use the Prefer header but to introduce a dedicated "please give me a 209" header.

209, on the other hand, makes sense to me. My litmus test for HTTP response codes is "Can a client, without domain specific knowledge, do something useful with the code?" If the answer is 'no' then re-use an existing code like 200 or 400. If 'yes' then adding a new code makes sense. In this case 209 seems to meet the bar so I am just using it and referencing draft-dusseault-http-patch-09 in my spec.

In reading sections 3 and 4 it would seem to a naïve reader (e.g. me) that Prefer: content-returned and 209 could be used with any method. But I could only figure out how to make it make sense for PUT/POST/PATCH. So in my own spec, at least for Web3S resources, I have restricted Web3SGetResponse and 209 to only be used on PUT/POST/PATCH (although we still use the name UPDATE, but that's a whole other discussion).

In my current spec I threw in some language that basically says that a 209 response might include content that goes beyond the changes in the associated method. E.g. in theory the following is legal according to my spec:
Time 0 - Issue PUT with Web3SGetResponse
Time 1 - PUT succeeds
Time 2 - Another method that changes the resource's state is successfully executed
Time 3 - The 209 response body to the PUT received at Time 0 is created and returned
It isn't clear to me if this behavior is legal according to the PATCH spec.

Also I put in some text that said that 209s can, in theory, be returned even if a client hasn't specified Web3SGetResponse but it isn't encouraged. I wasn't sure if this is legal according to the PATCH spec.

Just my two cents, your mileage may vary,

        Thanks,

                Yaron

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]]
> On Behalf Of James M Snell
> Sent: Wednesday, August 22, 2007 4:59 PM
> To: HTTP Working Group
> Subject: [Fwd: I-D ACTION:draft-dusseault-http-patch-09.txt]
>

---

From: James M Snell <[email-masked]>
Date: Wed, 29 Aug 2007 21:08:10 -0700

Grr... Yaron, I'm sure you're a good person and all but your mail
clients inability to wrap lines of text sucks. ;-)

In any case.. some comments below (with the quotes from you manually
wrapped ;-) ..)

Yaron Goland wrote:
> My current intention is to introduce a dedicated HTTP request header called "Web3SGetResponse" 
> whose semantics are the same as content-returned. The reason why I have chosen not to use Prefer 
> is that I am uncomfortable with placing all "safe to ignore" headers in HTTP into a single Prefer 
> header. In other words I can't figure out what kind of 'safe to ignore' header wouldn't end up in 
> Prefer and putting everything into Prefer just doesn't seem right.

The semantics of Prefer are clear... it's where the client can tell the
server what behaviors it would like the server to implement without
placing any requirements on the server.  While it certainly could be
overloaded to do lots of other things, doing so would definitely be a
mistake.  That possibility, however, does not lessen the value of the
Prefer header.

> 
> I choose the name "Web3SGetResponse" to indicate that I'm not trying to solve the general problem,
> I'm just solving a specific problem in the context of Web3S. If a more generic solution is agreed upon 
> I would be happy to use it. But my vote in that case would be not to use the Prefer header but to 
> introduce a dedicated "please give me a 209" header.

I'm all for solving specific problems with targeted solutions.  However,
this one in particular seems to be generic and broadly applicable enough
that a general solution is well waranted.

> 
> 209, on the other hand, makes sense to me. My litmus test for HTTP response codes is 
> "Can a client, without domain specific knowledge, do something useful with the code?" If the 
> answer is 'no' then re-use an existing code like 200 or 400. If 'yes' then adding a new code 
> makes sense. In this case 209 seems to meet the bar so I am just using it and referencing>
> draft-dusseault-http-patch-09 in my spec.
>

Good to hear.

> In reading sections 3 and 4 it would seem to a naïve reader (e.g. me) that 
> Prefer: content-returned and 209 could be used with any method. But I could only 
> figure out how to make it make sense for PUT/POST/PATCH. So in my own spec, at least
> for Web3S resources, I have restricted Web3SGetResponse and 209 to only be used on 
> PUT/POST/PATCH (although we still use the name UPDATE, but that's a whole other discussion).

That's perfectly fine.  Not all status codes make sense for all methods
in every case, that's true for all of the codes defined in RFC2616 and
its true for 209.

> 
> In my current spec I threw in some language that basically says that a 209 response 
> might include content that goes beyond the changes in the associated method. E.g. in 
> theory the following is legal according to my spec:

assuming that 0, 1 and 3 all fall within the scope of a single HTTP
request-response then yes, this should likely be the expected behavior.
 I wouldn't go so far as to say that it MUST work this way, however.

> 
> Also I put in some text that said that 209s can, in theory, be returned 
> even if a client hasn't specified Web3SGetResponse but it isn't encouraged. 
> I wasn't sure if this is legal according to the PATCH spec.

Yes, this would be fine.

- James

---

From: Henrik Nordstrom <[email-masked]>
Date: Thu, 30 Aug 2007 14:01:26 +0200

> Also I put in some text that said that 209s can, in theory, be returned even if a client hasn't specified Web3SGetResponse but it isn't encouraged. I wasn't sure if this is legal according to the P…

From what I can tell this family of race conditions is the main
motivation for the 209 response code.

Consider the following:

Time 0 - Client A issues PUT request
Time 1 - PUT 'A' succeeds
Time 3 - Client B issues PUT request
Time 4 - PUT 'B' succeeds
Time 5 - The response to the first PUT is generated, reflecting the
current content which is that of the second PUT, which is not at all
what the client expects.

Or to make a more interesting example

Time 0 - Client A issues PUT request
Time 1 - Put succeeds
Time 3 - Client B issues DELETE request
Time 4 - DELETE succeeds
Time 5 - The response to the first PUT is generated, but the resource is
now gone...

The other approach is using 204/201 with a cache validator. But this do
not allow the client access to the resulting resource after it's request
when this race occurs.

Time 0 - Client A issues PATCH request
Time 1 - PUT A succeeds, etag "1" returned.
Time 2 - Client B issues PATCH request
Time 3 - PUT B succeeds, etag "2" returned.
Time 4 - Client A issues conditional GET using etag "1", which fails
it's condition as the resource has been changed. It's now impossible for
Client A to get the results of it's request to verify how the
modifications was applied.

So the need for 209 would be to explicitly disallow this family of race
conditions, enabling the client access to the modified resource just
after the completetion of it's own request before any other
modification.

If 209 can not guarantee this then it's no better than using a
subsequent GET to fetch the modified resource if needed by the client.

Regards
Henrik