- From: Lisa Dusseault <lisa@osafoundation.org>
- Date: Sun, 21 Dec 2008 08:54:23 -0800
- 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 UTC