W3C home > Mailing lists > Public > ietf-http-wg@w3.org > October to December 2008

Re: Updated Patch

From: Lisa Dusseault <lisa@osafoundation.org>
Date: Sun, 21 Dec 2008 08:54:23 -0800
Message-Id: <F4BEAF4D-D05B-4FCB-97E6-11BAC1254023@osafoundation.org>
To: HTTP Working Group <ietf-http-wg@w3.org>, Julian Reschke <julian.reschke@gmx.de>


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
Received on Sunday, 21 December 2008 16:55:13 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Friday, 27 April 2012 06:50:58 GMT