Re: Updated Patch

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...


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.

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...


Editorial:

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

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.


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")


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)


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.


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>.


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.


BR, Julian

Received on Sunday, 6 January 2008 15:39:58 UTC