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
