Patch options -- summary of recent conversations

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

Received on Friday, 10 August 2007 17:00:58 UTC