Subject: Patch options -- summary of recent conversations

From: James M Snell <[email-masked]>
Date: Fri, 10 Aug 2007 10:00:45 -0700

Ok, so the recent conversations have been very helpful.  For PATCH it
appears that we have several options.

One... we could choose to create a new method

  PATCH /resource HTTP/1.1
  Content-Type: application/patch

  {patch format}

Or... since patch formats are identified by mime media type, it would be
possible to use POST and allow the server to derive the intention of the
request from the media type.

  POST /resource HTTP/1.1
  Content-Type: application/patch

  {patch format}

Valid arguments can be made for or against either approach.  The most
interesting of those involve the practicalities of deploying a new HTTP
method on existing infrastructure.  In theory, it's not supposed to be a
problem; in reality, unknown methods tend to be blocked by
intermediaries, making it quite likely that implementors will fall back
to methods that are known to get through.

Second... there's the question of how to return a representation of the
modified resource.

The first option is to use 200 OK with the Content-Location header.

  HTTP/1.1 200 OK
  Content-Location: /resource
  Content-Type: text/plain

  {foo}

At issue is whether or not this is unambiguous enough to work and
whether or not Content-Location will work effectively (Roy pointed out
the issues with reconstructing Content-Location when intermediaries are
involved).

The alternative approach would be to define a new status code:

  HTTP/1.1 209 Content Returned
  Content-Type: text/plain

  {foo}

A 209 response indicates that the response is exactly equivalent to what
would have been returned in a GET request issued immediately after the
modification request.  The new code is definitely unambiguous but
possibly unnecessary if 200+Content-Location will work.

Third, there's the question of allowing a client to opt-in/out of
receiving the modified version of the resource in the response.  The
default preference would be to opt-out with the decision ultimately
being left up to the server.

The options discussed have been to use either the Expect header or to
define a new Prefer header.

  Expect: 209-content-returned
  Expect: 204-no-content
  Prefer: 209-content-returned
  Prefer: 204-no-content

The challenge with Expect is that a) it is MUST understand and b)
intermediaries that do not understand the 209-content-returned might
block the request.

The Prefer header would get past those limitations by leaving the
decision of whether or not to honor the preference to the server.
Intermediaries would be required to forward the Prefer header and MAY
choose to honor it regardless of what the origin server does (e.g. the
proxy could choose to return a 204 if the client prefers even if the
server returns a 200 or 209).

I have not seen much discussion arguing against the Prefer header.  Are
there any reasons why it wouldn't work? Or are there any reasons why the
Prefer header would be a Bad Thing?

If we do end up going with the 209 status code and Prefer header, would
it make the most sense to separate those out into separate I-D's? Or
would people be comfortable with bundling those in with the PATCH draft?
 I'm fine with either.

- James

---

From: Henrik Nordstrom <[email-masked]>
Date: Fri, 10 Aug 2007 21:05:48 +0200

> Second... there's the question of how to return a representation of the

You CAN say that 200 OK always do that for PATCH. Does not really need a
new response type for PATCH.

The trouble only arises if you want the method to be able to selectively
return the new representation OR a successful status message entity
regarding the patch operation.

>   Content-Location: /resource

This discussion was more oriented towards POST than PATCH imho, trying
to find a rule where a 200 OK response entity could always be identified
as the requested respource regardless of the method involved, which is
not the case for POST where 200 OK may be just a informal status
message, or the modified entity, with no good indication of which is
being returned.

> the issues with reconstructing Content-Location when intermediaries are

Content-Location is an issue when there is reverse proxies involved
rewriting the requested URI before it's sent to the web server, making
the web server unaware of it's real URL.

Personally I would recommend nearly always returning 204 with a cache
validator allowing the client to request the resulting resource if it
wants it. I don't see much benefit in complicating the specification by
a conditional return of the modified resource when the same task can be
acheived by a followup method, and quite safely so thanks to cache
validators.

Regards
Henrik

---

From: "Mark Baker" <[email-masked]>
Date: Fri, 10 Aug 2007 15:24:43 -0400

On 8/10/07, James M Snell <[email-masked]> wrote:
> Valid arguments can be made for or against either approach.

I don't recall much of a discussion about using POST, but IMO it would
be inappropriate because POST provides no visibility into the ultimate
state of the targetted resource, whereas the action of "patching" a
resource requires it.

>  Prefer: 209-content-returned

I'd prefer the Prefer values not include the response code itself,
because other response codes may be used.  For example, a response to
a "Prefer: 209-content-returned" could be a 200 with Content-Location
if that's how the server wants to meet the preference.  Also, in the
future, other response codes might be defined which have a similar
meaning, and we don't want to prevent servers from using those.

> would people be comfortable with bundling those in with the PATCH draft?

I assume it would be less work to bundle them, so that would be my preference.

Mark.
-- 
Mark Baker.  Ottawa, Ontario, CANADA.         http://www.markbaker.ca
Coactus; Web-inspired integration strategies  http://www.coactus.com

---

From: David Morris <[email-masked]>
Date: Fri, 10 Aug 2007 13:00:04 -0700 (PDT)

> acheived by a followup method, and quite safely so thanks to cache

The problem that this doesn't cover is the care where two patches are
applied in rapid succession. Returning the result allow a client that
cares to compare the result with expectation to apply that level of
verification. The validator will not match when the first client makes its
request since the second client has already 'upgraded' the current
validator for the resource leaving the first belt and suspenders client
w/o an easy way to confirm correct application of the patch.

---

From: Lisa Dusseault <[email-masked]>
Date: Fri, 10 Aug 2007 13:50:03 -0700

>   Content-Type: application/patch

If the server advertises its support for this Content-Type somewhere,  
I could imagine this being sufficiently reliable.  I'm still a little  
worried that the server might respond successfully to a POST request  
without treating it as the client desires -- e.g. adding the request  
entity to an Atom collection, submitting it to a HTTP "drop-box",  
treating it as an alternative body for the resource, or one of the  
many things POST might already be used for out there.

I still prefer PATCH as a verb.

> the issues with reconstructing Content-Location when intermediaries  

Don't forget, there's also Content-MD5.  That could be used for the  
client to check whether the patched resource is exactly what the  
client would have gotten with a local application of the delta, or  
whether the server did some post-PATCH content mods (reformatting  
XML, adding metadata inside resource, etc).

Lisa

---

From: Jamie Lokier <[email-masked]>
Date: Sat, 11 Aug 2007 10:26:39 +0100

> many things POST might already be used for out there.

Quite a few resources out there will respond to PATCH by doing those
things anyway.  I've seen quite a few CGI scripts and libraries which
will respond to all requests as though they are POST, unless they are
GET/HEAD.

So you always have to know a bit about which resource you're PATCHing
or POSTing.

> I still prefer PATCH as a verb.

Makes sense to me.

-- Jamie

---

From: Henrik Nordstrom <[email-masked]>
Date: Sat, 11 Aug 2007 11:38:25 +0200

> I still prefer PATCH as a verb.

Yes. Specifying it using POST is backwards and not in line with the
spirit of HTTP.

Regards
Henrik

---

From: Julian Reschke <[email-masked]>
Date: Sun, 12 Aug 2007 15:32:16 +0200

> appears that we have several options.

James, thanks for the summary.

> to methods that are known to get through.

The problem is that

a) you will need out-of-band information about the resource; does it 
understand POST with a patch body as expected?

b) it will make it impossible to implement this for a resource that 
already uses POST for something else, such as an AtomPub collection. You 
would need to mint a new URI for accessing the patch semantics. Ugly.

> ...

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Sun, 12 Aug 2007 15:34:10 +0200

> w/o an easy way to confirm correct application of the patch.

David,

that's correct, but I'm not sure whether this is a problem in practice. 
If there's a race condition, the client will not know what the resulting 
  entity for the original PATCH request was. But why would it matter? 
Somebody else modified it in the meantime anyway...

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Sun, 12 Aug 2007 15:37:00 +0200

> So you always have to know a bit about which resource you're PATCHing

But at least OPTIONS/Allow will tell us whether the server has any idea 
what PATCH is, right?

Best regards, Julian

---

From: Jamie Lokier <[email-masked]>
Date: Sun, 12 Aug 2007 15:52:18 +0100

> But at least OPTIONS/Allow will tell us whether the server has any idea 

If you're lucky.  If you're not lucky, the server will treat OPTIONS
like GET or POST, or something else.

For example, as far as I can tell, any Perl CGI script which uses the
standard CGI.pm Perl module will probably treat OPTIONS as though it
is a GET request but ignore the query part of the URL.

Perhaps it's not a problem: you'll get a response with no Allow
header.

That's because it has some bits of code which compare method against
'POST', and some bits which compare against 'GET|HEAD'.  Yes it's poor
programming, but it's widely deployed - it's the standard way to do
Perl CGI, and also Apache with mod_perl, if you're not using some
other framework.

I've seen other (non-Perl) code which similarly assumes it is always
called with GET/HEAD/POST, and effectively defaults to one of them if
another method is used.

That includes the OPTIONS method.  So it might be unwise to depend on
OPTIONS without at least _some_ out of band knowledge that it's safe
to use on a particular resource.

-- Jamie

---

From: Julian Reschke <[email-masked]>
Date: Sun, 12 Aug 2007 18:44:56 +0200

> like GET or POST, or something else.

In which case it won't return "Allow: PATCH", right?

Best regards, Julian

---

From: Jamie Lokier <[email-masked]>
Date: Sun, 12 Aug 2007 19:51:39 +0100

> In which case it won't return "Allow: PATCH", right?

That's right, but it may have unwanted side effects similar to POST,
so you shouldn't use OPTIONS indiscriminately.

Then again, you shouldn't be trying to PATCH a resource you don't know
is patchable anyway.

My point is if you don't know it's patchable, you shouldn't be trying
PATCH _or_ OPTIONS on it.

If you do know it's patchable, then using PATCH as a verb, or the
suggested alternative POST with Content-Type: application/patch seem
equally usable.  PATCH is more in keeping with the rest of HTTP (PUT,
DELETE etc.)

It's been suggested than PATCH will have problems with some
intermediaries.  But PUT etc. also has problems with intermediaries
(probably the same ones), and I imagine most uses of PATCH expect PUT
to work as well.  This is an argument in favour of PATCH as a verb.

-- Jamie

---

From: Julian Reschke <[email-masked]>
Date: Sun, 12 Aug 2007 21:02:08 +0200

> so you shouldn't use OPTIONS indiscriminately.

With the amount of OPTIONS requests sent out today by WebDAV clients, 
I'd really be surprised if there are important pieces of software left 
that cause side effects upon OPTIONS.

Do you have any evidence of that?

> Then again, you shouldn't be trying to PATCH a resource you don't know

The way to find out whether something is patchable, is to either just 
try the request and let it fail, or to poll with OPTIONS in advance. 
This is what RFC2616 says.

> PATCH _or_ OPTIONS on it.

I think that's bad advice. I've been working on WebDAV related clients 
and servers for several years now, and was also involved in customer 
support, and have never ever heard of a piece of software 
misunderstanding OPTIONS, causing a side effect.

Best regards, Julian

---

From: Henrik Nordstrom <[email-masked]>
Date: Mon, 13 Aug 2007 00:04:58 +0200

> that cause side effects upon OPTIONS.

There is pleny, but also very unlikely WebDAV or PATCH would be used on
such resources.

Regards
Henrik

---

From: Julian Reschke <[email-masked]>
Date: Mon, 13 Aug 2007 09:37:33 +0200

> There is pleny, but also very unlikely WebDAV or PATCH would be used on

WebDAV clients routinely use OPTIONS to detect whether they *can* use 
WebDAV on a resource. Think Microsoft Office (and don't tell me that's 
not widely used :-).

Best regards, Julian

---

From: Henrik Nordstrom <[email-masked]>
Date: Mon, 13 Aug 2007 10:55:33 +0200

> WebDAV on a resource. Think Microsoft Office (and don't tell me that's 

Yes, but it requires the user to take some action to activate the WebDAV
client, which he isn't very likely to do against random CGI URLs other
websites.

Sure it may happen, but not in a context where it's expected to yield
any directly meaningful results.

Regards
Henrik

---

From: Julian Reschke <[email-masked]>
Date: Mon, 13 Aug 2007 11:04:54 +0200

> client, which he isn't very likely to do against random CGI URLs other

That's not really true. The Office WebDAV stack kicks in as soon as you 
navigate to an office document.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Mon, 13 Aug 2007 13:45:27 +0200

> navigate to an office document.

(when using IE, of course)

Best regards, Julian

---

From: "Roy T. Fielding" <[email-masked]>
Date: Mon, 13 Aug 2007 11:24:41 -0700

> any directly meaningful results.

Folks, this is an irrelevant conversation.  HTTP is not defined by
individual broken implementations, and certainly never by broken CGI
scripts.  The standard needs to reflect how PROPERLY implemented
applications can interoperate, not how the least capable programmer
of the day makes mistakes.  Broken implementations can be fixed much
faster than a thousand vendors can agree on a standard.

....Roy