Subject: Re: Updated Patch

From: Lisa Dusseault <[email-masked]>
Date: Sun, 21 Dec 2008 08:54:23 -0800

Attempting to resolve the few remaining open issues on HTTP PATCH --  
'm replying to a mail from Julian to this list, sent Jan 06 2008.  I  
pulled it off the Web archive, however, so this email won't have the  
normal reply-to headers.

> Hi James,
>
> below are some change suggestions and questions:
>
> Questions:
>
> Section 2., paragraph 6:
> OLD:
>
>     It is RECOMMENDED that servers return a 501 (Not Implemented)
>     response if a PATCH request contains any entity-headers the server
>     does not understand.  Unexpected or unintended results can occur  
> if a
>     server ignores known or unknown entity headers included in the
>     request.  All entity-headers contained in the request apply only  
> to
>     the contained patch document and MUST NOT be applied to the  
> resource
>     being modified.
>
> I can't recall why we're making this requirement; it seems to copy a
> requirement for PUT. However, for PUT, "applying an entity header"  
> just
> means storing it. What does it mean for PATCH? This introduces a
> "must-understand" rule without knowing what "understand" precisely  
> means...

This seems to have gotten broken unintentionally.  It used to read  
"The server MUST NOT ignore any Content-* headers".  That's a much  
more reasonable requirement, because the server can tell what headers  
are Content-* headers while it can't tell what entity-headers are. And  
the requirement to understand the Content-* headers means that the  
server knows what to do with it which depends on : to save the Content- 
Type or Content-Language as metadata, to confirm or ignore the Content- 
Length, etc.

>
>
> Section 3.1., paragraph 3:
> OLD:
>
>     The Accept-Patch header specifies a comma separated listing of  
> media-
>     types as defined by [RFC2616], Section 3.7.  The asterisk  
> character
>     "*" MAY be used to indicate that any patch format is accepted.
>
> You may want to state that the ABNF is the one used in RFC2616, not  
> RFC5234.

That would be good.

>
> Section 6., paragraph 1:
> OLD:
>
>     The security considerations for PATCH are nearly identical to the
>     security considerations for PUT.  In addition, one might be  
> concerned
>     that a document that is patched might be more likely to be  
> corrupted,
>     but that concern can be addressed through the use of mechanisms  
> such
>     as conditional requests using ETags and the If-Match request  
> header.
>
> I don't think RFC2616 has any specific ones for PUT, so this is a bit
> misleading...

I hope that the security considerations for PUT will shortly be  
updated :)

>
>
> Editorial:
>
> - I noticed a broken internal Section link; you may check all them,
> optimally using xml2rfc to keep track of them.

There's an xml2rfc version of the doc.

>
> Other than that:
>
>
> 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.

OK

>
>
> Section 2., paragraph 3:
> OLD:
>
>     The server MUST apply the entire set of changes atomically and  
> never
>     provide (e.g. in response to a GET during this operation) a
>     partially-modified representation.  If the entire patch document
>     cannot be successfully applied then the server MUST fail the  
> entire
>     request, applying none of the changes.  The determination of what
>     constitutes a successful PATCH can vary depending on the patch
>     document and the type of resource being modified.  The actual  
> method
>     for determining how to apply the patch document to the resource is
>     defined entirely by the origin server.  See Error Handling in  
> section
>     2.2 for details on status codes and possible error conditions.
>
> NEW:
>
>     The server MUST apply the entire set of changes atomically and  
> never
>     provide (e.g. in response to a GET during this operation) a
>     partially-modified representation.  If the entire patch document
>     cannot be successfully applied then the server MUST fail the  
> entire
>     request, applying none of the changes.  The determination of what
>     constitutes a successful PATCH can vary depending on the patch
>     document and the type of resource being modified.  The actual  
> method
>     for determining how to apply the patch document to the resource is
>     defined entirely by the origin server.  See Error Handling in
>     Section 2.2 for details on status codes and possible error
>     conditions.
>
> (uppercase "Section")

OK

>
>
> Section 2.2., paragraph 2:
> OLD:
>
>     Malformed patch document:  Can be specified using a 400 Bad  
> Request
>        when the server finds that the patch document provided by the
>        client was not properly formatted.  The definition of badly
>        formatted depends on the patch document chosen, but generally  
> if
>        the server finds it cannot handle the patch due to the
>        serialization of the patch document, this response ought to be
>        appropriate.
>     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.
>     Unprocessable request:  Can be specified with a 422 Unprocessable
>        Entity [RFC4918] when the server understands the patch document
>        and the syntax of the patch document appears valid, but the  
> server
>        is incapable of processing the request.  There are a number of
>        situations that could lead to such a result, for example:
>        *  The client attempted to apply a patch document to an empty  
> or
>           non-existent resource, but the patch document chosen  
> cannot be
>           applied to an empty or non-existent resource.
>        *  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.
>
> NEW:
>
>     Malformed patch document:  Can be specified using a 400 (Bad  
> Request)
>        status when the server finds that the patch document provided  
> by
>        the client was not properly formatted.  The definition of badly
>        formatted depends on the patch document format chosen, but
>        generally if the server finds it cannot handle the patch due to
>        the serialization of the patch document, this response ought  
> to be
>        appropriate.
>     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.
>     Unprocessable request:  Can be specified with a 422 (Unprocessable
>        Entity) status [RFC4918] when the server understands the patch
>        document and the syntax of the patch document appears valid,  
> but
>        the server is incapable of processing the request.  There are a
>        number of situations that could lead to such a result, for
>        example:
>        *  The client attempted to apply a patch document to an empty  
> or
>           non-existent resource, but the patch document chosen  
> cannot be
>           applied to an empty or non-existent resource.
>        *  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.
>
> (use "NNN (Reason Phrase) status" format throughout)

OK

>
>
> Section 2.2., paragraph 3:
> OLD:
>
>     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.
>
> NEW:
>
>     Conflicting modification:  Specified with a 412 (Precondition  
> Failed)
>        status 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) status 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) status until the first
>        modification request is complete.

OK

>
>
> Section 5.2., paragraph 1:
> OLD:
>
>     This specification defines the 209 Content Returned status code
>     (Section 3) to be updated in the registry at
>     <http://www.iana.org/assignments/http-status-codes>.
>
> NEW:
>
>     This specification defines the 209 Content Returned status code
>     (Section 4) to be updated in the registry at
>     <http://www.iana.org/assignments/http-status-codes>.

OK

>
>
> Section 6., paragraph 1:
> OLD:
>
>     The security considerations for PATCH are nearly identical to the
>     security considerations for PUT.  In addition, one might be  
> concerned
>     that a document that is patched might be more likely to be  
> corrupted,
>     but that concern can be addressed through the use of mechanisms  
> such
>     as conditional requests using ETags and the If-Match request  
> header.
>
> NEW:
>
>     The security considerations for PATCH are nearly identical to the
>     security considerations for PUT .  In addition, one might be
>     concerned that a document that is patched might be more likely  
> to be
>     corrupted, but that concern can be addressed through the use of
>     mechanisms such as conditional requests using ETags and the If- 
> Match
>     request header.

OK

Lisa

---

From: Julian Reschke <[email-masked]>
Date: Mon, 22 Dec 2008 11:47:37 +0100

Lisa Dusseault wrote:
>> requirement for PUT. However, for PUT, "applying an entity header" just
> This seems to have gotten broken unintentionally.  It used to read "The 
> server MUST NOT ignore any Content-* headers".  That's a much more 
> reasonable requirement, because the server can tell what headers are 
> Content-* headers while it can't tell what entity-headers are. And the 
> requirement to understand the Content-* headers means that the server 
> knows what to do with it which depends on : to save the Content-Type or 
> Content-Language as metadata, to confirm or ignore the Content-Length, etc.

Well, RFC 2616 says that any header that is not a request or general 
header is an entity header. And yes, this is not really true in practice.

An no, the entity header, thus the Content-* headers do *not* apply to 
the resource being patched, but to the payload. So when I use 
Content-Type: application/diff in a PATCH request, I do *not* want that 
to be set on the resource being patched :-).

>>     security considerations for PUT.  In addition, one might be concerned
>>     that a document that is patched might be more likely to be corrupted,
>>     but that concern can be addressed through the use of mechanisms such
>>     as conditional requests using ETags and the If-Match request header.
>>
> I hope that the security considerations for PUT will shortly be updated :)

That may be the case (do you have something specific in mind?), but as 
long as the draft refers to RFC2616 some rephrasing seems to be in order 
:-).

> There's an xml2rfc version of the doc.

Yes, but apparently not all internal links are marked up as such.

> ...

BR, Julian

---

From: Lisa Dusseault <[email-masked]>
Date: Mon, 22 Dec 2008 09:03:02 -0800

On Dec 22, 2008, at 2:47 AM, Julian Reschke wrote:

>> more reasonable requirement, because the server can tell what  
>> headers are Content-* headers while it can't tell what entity- 
>> headers are. And the requirement to understand the Content-*  
>> headers means that the server knows what to do with it which  
>> depends on : to save the Content-Type or Content-Language as  
>> metadata, to confirm or ignore the Content-Length, etc.
>
> An no, the entity header, thus the Content-* headers do *not* apply  
> to the resource being patched, but to the payload. So when I use  
> Content-Type: application/diff in a PATCH request, I do *not* want  
> that to be set on the resource being patched :-).

If I had a better memory, I wouldn't have circular arguments like  
this.  Argh.  Yeah, Content-Type is universally used to indicate the  
content of the payload, and shouldn't be used to change the Content- 
Type of the resource being patched.

There is a minor problem of Content-Language, I think the other  
Content-* headers are even more irrelevant.  How many systems out  
there actually save the Content-Language provided by the client in a  
PUT?  And for those systems, is the only way to change the Content- 
Language to issue another whole PUT?  What would those systems want a  
PATCH with a Content-Language to mean -- (1) "This is the new Content- 
Language for the resource, please save it" or (2) "This is the  
language of the PATCH payload so it's irrelevant, throw it away" or  
(3) illegal.

thanks,

Lisa

---

From: Julian Reschke <[email-masked]>
Date: Mon, 22 Dec 2008 18:15:53 +0100

Lisa Dusseault wrote:
> ...
> If I had a better memory, I wouldn't have circular arguments like this.  
> Argh.  Yeah, Content-Type is universally used to indicate the content of 
> the payload, and shouldn't be used to change the Content-Type of the 
> resource being patched.
> ...

s/shouldn't/can't/

> Content-* headers are even more irrelevant.  How many systems out there 
> actually save the Content-Language provided by the client in a PUT?  And 

Some, at least (I wrote parts of one).

> for those systems, is the only way to change the Content-Language to 
> issue another whole PUT?  What would those systems want a PATCH with a 
> Content-Language to mean -- (1) "This is the new Content-Language for 
> the resource, please save it" or (2) "This is the language of the PATCH 
> payload so it's irrelevant, throw it away" or (3) illegal.

If *editing* of existing entity headers is needed, we *could* define a 
specific format (+ mime type) for it.

So far, I'm not convinced it's needed, though...

BR, Julian

---

From: Cyrus Daboo <[email-masked]>
Date: Mon, 22 Dec 2008 15:30:10 -0500

Hi Lisa,

--On December 22, 2008 9:03:02 AM -0800 Lisa Dusseault 
<[email-masked]> wrote:

> There is a minor problem of Content-Language, I think the other Content-*
> headers are even more irrelevant.  How many systems out there actually
> save the Content-Language provided by the client in a PUT?  And for those
> systems, is the only way to change the Content-Language to issue another
> whole PUT?  What would those systems want a PATCH with a Content-Language
> to mean -- (1) "This is the new Content-Language for the resource, please
> save it" or (2) "This is the language of the PATCH payload so it's
> irrelevant, throw it away" or (3) illegal.

Well Content-Language is supposed to map to the DAV:getcontentlanguage 
property. So if a server does save it, clients have a way to change it 
directly via PROPPATCH.

So as Julian noted the Content-* on the PATCH should apply only to the 
PATCH request data - they should not be used to change the properties on 
the resource being PATCH's. Instead clients can use PROPPATCH to do that. 
Which begs the question as to whether there is a need to have an atomic 
"patch the body and properties" operation i.e. atomic PATCH + PROPPATCH. I 
guess with LOCK you could do that. The alternative is to specify a patch 
format that allows for patching the body and updating properties at the 
same time.

-- 
Cyrus Daboo