Subject: PATCH draft

From: "Lisa Dusseault" <[email-masked]>
Date: Mon, 26 Jan 2009 17:54:22 +0000

Julian helped me get another draft of this out that fixes his issues:

http://tools.ietf.org/html/draft-dusseault-http-patch-12

I've had so many groups ask for this over the years that I'm embarrassed  
it has taken this long.  Please provide final comments shortly and I'll  
try to get it done.

Thanks,
Lisa Dusseault

--- Scanned by M+ Guardian Messaging Firewall ---
Messaging Architects sponsors The Spamhaus Project.

---

From: James M Snell <[email-masked]>
Date: Tue, 27 Jan 2009 08:40:36 -0800

Thank you. I should be the one to apologize on this. I had an 
outstanding todo to complete this for quite a while now. I appreciate 
you and Julian getting it done.

- James

Lisa Dusseault wrote:
> I've had so many groups ask for this over the years that I'm 
> embarrassed it has taken this long.  Please provide final comments 
> shortly and I'll try to get it done.
>
> Thanks,
> Lisa Dusseault
>

---

From: Julian Reschke <[email-masked]>
Date: Fri, 30 Jan 2009 14:17:02 +0100

Lisa Dusseault wrote:
> ...

OK, here's new feedback, most of which are nits:

INTRODUCTION, paragraph 14:
OLD:

    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.

NEW:

    Several applications extending the Hypertext Transfer Protocol (HTTP)
    require a feature to do partial resource modification.  The existing
    HTTP PUT method only allows a complete replacement of a document.
    This proposal adds a new HTTP method, PATCH, to modify an existing
    HTTP resource.

(expand HTTP acronym on first use; probably should also be done in the 
title)

Section 1., paragraph 1:
OLD:

    This specification defines the new HTTP 1.1 [RFC2616] method PATCH
    that is used to apply partial modifications to a resource.

NEW:

    This specification defines the new HTTP/1.1 [RFC2616] method PATCH
    that is used to apply partial modifications to a resource.

s|HTTP 1.1|HTTP/1.1|

Section 2., paragraph 1:
OLD:

    The PATCH method requests that a set of changes described in the
    request entity be applied to the resource identified by the Request-
    URI.  The set of changes is represented in a format called a "patch
    document" identified by a media type.  PATCH is neither safe or
    idempotent as defined by [RFC2616], Section 9.1.  If the Request-URI
    does not point to an existing resource, and that URI is capable of
    being defined as a new resource by the requesting user agent, the
    origin server can create the resource with that URI.

NEW:

    The PATCH method requests that a set of changes described in the
    request entity be applied to the resource identified by the Request-
    URI.  The set of changes is represented in a format called a "patch
    document" identified by a media type.  If the Request-URI does not
    point to an existing resource, and that URI is capable of being
    defined as a new resource by the requesting user agent, the origin
    server can create the resource with that URI.

    PATCH is neither safe nor idempotent as defined by [RFC2616], Section
    9.1.

(pull statement about safety into separate paragraph)

Section 2., paragraph 4:
OLD:

    If the request passes through a cache and the Request-URI identifies
    one or more currently cached entities, those entries SHOULD be
    treated as stale.  Responses to this method are not cacheable, unless
    the response includes appropriate Cache-Control or Expires header
    fields or the response uses the 209 Content Returned status code as
    defined in Section 4.  The 303 (See Other) response can be used to
    direct the user agent to retrieve a cacheable resource.

NEW:

    If the request passes through a cache and the Request-URI identifies
    one or more currently cached entities, those entries SHOULD be
    treated as stale.  Responses to this method are not cacheable, unless
    the response includes appropriate Cache-Control or Expires header
    fields or the response uses the 209 Content Returned status code as
    defined in Section 4.  The 303 (See Other) response can be used to
    direct the user agent to retrieve a cacheable resource. [[anchor1:
    ???]]

I'm not totally sure why we'd want 303 here. What's wrong with 200; it's 
not like the 303 ever would include a different URI in the Location 
header, right?

Section 2., paragraph 5:
OLD:

    Collisions from multiple requests are more dangerous than PUT
    collisions, because a patch document that is not operating from a
    known base point may corrupt the resource.  Clients wishing to apply
    a patch document to a known entity can first acquire the strong ETag
    of the resource to be modified, and use that Etag in the If-Match
    header on the PATCH request to verify that the resource is still
    unchanged.  If a strong ETag is not available for a given resource,
    the client can use If-Unmodified-Since as a less-reliable safeguard.

NEW:

    Collisions from multiple requests are more dangerous than PUT
    collisions, because a patch document that is not operating from a
    known base point may corrupt the resource.  Clients wishing to apply
    a patch document to a known entity can first acquire the ETag of the
    resource to be modified, and use that Etag in the If-Match header on
    the PATCH request to verify that the resource is still unchanged.  If
    an ETag is not available for a given resource, the client can use If-
    Unmodified-Since as a less-reliable safeguard.

Why exactly do we require a strong etag here in general?

Section 2.2., paragraph 2:
OLD:

    Unsupported patch document:  Can be Specified using a 415
       (Unsupported Media Type) when the client sends a patch document
       format that the server does not support for the resource
       identified by the Request-URI.  Such a response SHOULD include an
       Accept-Patch response header as described in Section 3.1 to notify
       the client what patch document formats are supported.

NEW:
    Unsupported patch document:  Can be specified using a 415
       (Unsupported Media Type) when the client sends a patch document
       format that the server does not support for the resource
       identified by the Request-URI.  Such a response SHOULD include an
       Accept-Patch response header as described in Section 3.1 to notify
       the client what patch document formats are supported.

s/S/s/

Section 2.2., paragraph 3:
OLD:

       *  The client attempted to apply a structural modification and the
          structures assumed to exist did not exist (e.g. a patch which
          specifies changing element 'foo' to element 'bar' but element
          'foo' doesn't exist).
       *  The client attempted to modify a resource in a way that would
          cause the resource to become invalid.  For instance, a
          modification to a well-formed XML document that would cause it
          to no longer be well-formed.
       *  The client attempted to modify a resource that has multiple
          representations but the server was unable to choose which
          representation to modify.
    Conflicting modification:  Specified with a 412 (Precondition Failed)
       when a client uses either the If-Match or If-Unmodified-Since
       request headers and attempts to apply a patch document to a
       resource whose state has changed since the patch was created.  If
       the server detects a possible conflicting modification and neither
       the If-Match or If-Unmodified-Since request headers are used, the
       server can return a 409 (Conflict) response.
    Concurrent modification:  When a server receives multiple concurrent
       requests to modify a resource, those requests SHOULD be queued and
       processed in the order in which they are received.  If a server is
       incapable of queuing concurrent requests, all subsequent requests
       SHOULD be rejected with a 409 (Conflict) until the first
       modification request is complete.

I think in all these cases 422 is not the right choice, because the 
problem is not with the request, but the state of the resource.  Thus it 
seems 409 Conflict would be better.

Section 3.1., paragraph 3:
OLD:

  3.2.  An example OPTIONS request and response

NEW:

  3.2.  An example OPTIONS Request and Response

(title case)

Appendix A., paragraph 1:
OLD:

     PATCH is not a new concept, it first appeared in HTTP in drafts of
     version 1.1 written by Roy Fielding and Henrik Frystyk and also
     appears in RFC 2068.

NEW:

     PATCH is not a new concept, it first appeared in HTTP in drafts of
     version 1.1 written by Roy Fielding and Henrik Frystyk and also
     appears in Section 19.6.1.1 of RFC 2068.

(point to specific section of RFC 2068)

BR, Julian

---

From: Cyrus Daboo <[email-masked]>
Date: Fri, 30 Jan 2009 11:15:02 -0500

Hi Lisa,

> it has taken this long.  Please provide final comments shortly and I'll

- In the example in Section 2.1 there is a Content-MD5 header in the 
response. What does that refer to? The actual response body is empty.

- Security: PATCH will likely require the server to use a lot more CPU than 
a straight PUT. If someone were to define an "active" patch format (e.g. 
one with a repeat or loop capability), then a malicious client could use 
that as a denial-of-service vector. Can we add text like the following to 
Security Considerations:

    Servers MUST take adequate precautions to ensure that malicious
    clients cannot consume excessive server resources (e.g., CPU, disk I/O)
    through the client's use of PATCH.

Isn't there a response code for the server to indicate it is giving up 
processing because the client request has consumed too much e.g., CPU?

- There should be some statement in the document along the lines of:

    Clients need to make a smart choice on when it is applicable to use
    PATCH rather than PUT. For example, if the patch document size is
    larger than the size of the new resource data that would be used in a
    PUT, then it probably makes sense to use PUT instead of PATCH.

-- 
Cyrus Daboo

---

From: Cyrus Daboo <[email-masked]>
Date: Fri, 30 Jan 2009 11:33:32 -0500

Hi Lisa,

> it has taken this long.  Please provide final comments shortly and I'll

Another comment: this draft defines the new 209 status code, yet it does 
not clearly explain under what circumstances a server would return the 
resulting resource data in the PATCH response. Is that something the server 
chooses to do unilaterally, or does the client get to ask the server to 
return the result?

Note that in CalDAV we have the situation now where pretty much every PUT 
of a resource has to be followed by a GET because the server is modifying 
the resource to account for scheduling actions that happen synchronously. 
It would be nice if there were a way for a client to ask the server to 
return the (now modified) resource in the PUT response with a 209 status 
code.

-- 
Cyrus Daboo

---

From: Julian Reschke <[email-masked]>
Date: Fri, 30 Jan 2009 17:39:15 +0100

> response. What does that refer to? The actual response body is empty.

Right. This contradicts the definition of Content-MD5 
(<http://greenbytes.de/tech/webdav/rfc2616.html#rfc.section.14.15>), so 
it probably would be good to remove it.

That being said: I think the HTTPbis definition of Content-MD5 should be 
changed so that it can be sent with a 204 as updated metadata. (new issue?)

> - Security: PATCH will likely require the server to use a lot more CPU 
> than a straight PUT. If someone were to define an "active" patch format 
> (e.g. one with a repeat or loop capability), then a malicious client 
> could use that as a denial-of-service vector. Can we add text like the 
> following to Security Considerations:
> 

+1, except I don't think we need BCP14 language here. It's sufficient to 
make implementors aware of the problem.

> processing because the client request has consumed too much e.g., CPU?

I don't think so... Do we need one for interop?

>    PUT, then it probably makes sense to use PUT instead of PATCH.

I do not disagree with the statement, but I'm also not sure it *needs* 
to be stated (so +-0 on that).

BR, Julian

---

From: Julian Reschke <[email-masked]>
Date: Fri, 30 Jan 2009 18:01:00 +0100

Cyrus Daboo wrote:
> resulting resource data in the PATCH response. Is that something the 
> server chooses to do unilaterally, or does the client get to ask the 
> server to return the result?
> 
> Note that in CalDAV we have the situation now where pretty much every 
> PUT of a resource has to be followed by a GET because the server is 
> modifying the resource to account for scheduling actions that happen 
> synchronously. It would be nice if there were a way for a client to ask 
> the server to return the (now modified) resource in the PUT response 
> with a 209 status code.
> ...

I think what you're looking for is 
<http://tools.ietf.org/html/draft-snell-http-prefer-00>. This used to be 
in the PATCH I-D, but James moved it into a separate spec (which I think 
was a good idea in order to keep PATCH as simple as possible).

BR, Julian

---

From: Cyrus Daboo <[email-masked]>
Date: Fri, 30 Jan 2009 15:50:56 -0500

Hi Julian,

> was a good idea in order to keep PATCH as simple as possible).

Yes, that looks good, but it is expired.

However, the definition of 209 in PATCH still seems a little odd without 
reference to that. Is 209 absolutely needed in PATCH? Could that instead be 
moved to James document as a separate section describing the interaction of 
Prefer and PATCH? Alternatively we could progress James document at the 
same time as PATCH and cross-reference - but maybe we don't want to delay 
PATCH.

-- 
Cyrus Daboo

---

From: Julian Reschke <[email-masked]>
Date: Fri, 30 Jan 2009 22:07:39 +0100

Cyrus Daboo wrote:
> reference to that. Is 209 absolutely needed in PATCH? Could that instead 
> be moved to James document as a separate section describing the 
> interaction of Prefer and PATCH? Alternatively we could progress James 
> document at the same time as PATCH and cross-reference - but maybe we 
> don't want to delay PATCH.

I wouldn't object to making the PATCH I-D even simpler, and to move 209 
somewhere else.

BR, Julian

---

From: James M Snell <[email-masked]>
Date: Fri, 30 Jan 2009 14:10:00 -0800

That would be fine. The 209 response code is not critical in this case.

Regarding the Prefers header draft... if there is enough interest, I 
will revive it. I let it expire because there did not appear to be 
enough interest in pursuing it.

- James

Julian Reschke wrote:
>> However, the definition of 209 in PATCH still seems a little odd 
>> without reference to that. Is 209 absolutely needed in PATCH? Could 
>> that instead be moved to James document as a separate section 
>> describing the interaction of Prefer and PATCH? Alternatively we 
>> could progress James document at the same time as PATCH and 
>> cross-reference - but maybe we don't want to delay PATCH.
>
> I wouldn't object to making the PATCH I-D even simpler, and to move 
> 209 somewhere else.
>
> BR, Julian
>
>

---

From: "Roy T. Fielding" <[email-masked]>
Date: Fri, 30 Jan 2009 15:10:33 -0800

I think my earlier comments still hold: 209 is not needed anywhere
because that functionality is already covered by Content-Location.

....Roy