Re: FYI: I-D ACTION:draft-dusseault-http-patch-02.txt

I'm putting together another draft before the July deadline, let's see 
if we can get closer to agreement this time.  I appreciate where the 
comments came with constructive suggestions; in those cases it made it 
much easier to deal with the comments.

On May 21, 2004, at 3:45 PM, Roy T. Fielding wrote:

>
>> http://www.ietf.org/internet-drafts/draft-dusseault-http-patch-02.txt
>
> I cannot support the following changes to the PATCH method, since
> they serve no useful purpose and add complexity to HTTP.
>
> The IM header field serves no other purpose than to duplicate
> what content-type is already defined to perform, and has the
> added complexity ...

Yeah, I had misgivings myself putting that into draft-02.  I'll see 
what it takes to register the MIME type for at least one of vcdiff or 
gdiff.

> There is no reason to require that the resource already exists
> (such a requirement is nonsensical in any case, since in HTTP the
> resource is the temporal invariance found in mapping of URI to content,
> not some file in storage).  The requirement should be that the PATCH
> media type define whether an existing representation is necessary
> or not, which is trivial for the server to discover when applying
> the patch (it is a conflict, like any other conflict).

Some patch formats don't allow for being applied to a "null file".  
Rather than allow the delta format to dictate whether this is allowed 
and choose an error in case it might not, I thought it made the spec 
simpler to say that PATCH cannot be used to apply a delta to a 
"previously unmapped URL".  This means that the error response can be 
depended on and server and client implementation ought to be simpler.  
It's a real corner-case to want to PATCH a new, empty resource, and it 
may easily be an unintended action on the part of the client -- the 
client may believe that the resource exists (yes, If-Match can be used 
to confirm this, but PATCH can make it easier).

If it's the wording that results in what you believe is nonsensical, is 
there some other wording?  At times the WebDAV group has used "unmapped 
URL" instead of "resource that does not exist".  Would that fix the 
problem?

>
> There is no reason to require that PATCH be subject to the same
> access controls as PUT.  The methods are orthogonal and implementers
> do not need to be constrained.  Yes, that is a logical implication
> for use of WebDAV ACLs, but that doesn't make it a requirement
> on all implementations.

I've amended this with "If the server supports WebDAV ACLs...".  It's a 
SHOULD requirement so that implementations can diverge if they need to. 
  Another option would be to say that servers MUST either make PATCH 
follow the same access controls as PUT, or they MUST define a new 
permission named 'patch'... but I don't see this really being used in 
practice.  The intent here is to give clients some idea whether to 
enable functions that use PATCH after querying the server to see what 
the current user's privileges are.  The explicit information on how to 
work with WebDAV ACLs  was suggested by Chris Sharp on his review of 
the -00 draft.

>
> "The PATCH request MUST only be used in a context which ensures
> that only one user may apply a patch at a time ..." assumes a
> particular application (content replication) that is not necessary
> as a requirement on the protocol. In particular, this requirement
> disallows the primary purpose of the original PATCH method, which
> was to support collaborations among multiple authors working on
> different parts of the same representation.  Yes, conflicts are
> possible in such situations, but they can be handled by the process
> of applying each PATCH and responding with appropriate error codes --
> they do not need to be legislated out of existence by overzealous
> standards.  In fact, most reliable differencing mechanisms include
> content verification via context or hashing; there is no need to
> require that the simple HTTP mechanisms of Etag and If-Match be used
> when the client is capable of making that choice on their own, and
> the server is capable of handling that choice based on the existing
> HTTP/1.1 protocol and orthogonal to the definition of PATCH.
> Requirements within the core protocol must be reserved for design
> decisions that are necessary for interoperability, not those that
> are dependent on a particular application of that protocol.

The intent of this language was to be extra safe about having the 
client apply the PATCH method to a known starting-point.  Some delta 
formats could corrupt the files if they are applied to the wrong 
version.  Rather than leave this up to the delta format defined, it 
seemed more consistent, and not too constraining, to make this 
constraint for all delta formats.

Despite what I believe to be the correctness of the intent, I could go 
along with weakening this -- however, I suspect not everybody in the 
mailing list would agree.  Julian Reschke suggested that the use of 
strong ETags (or locks) be a MUST to reduce chances of corrupting files 
by applying a delta to the wrong version.  Julian can confirm whether 
that indicates support for this restriction.

>
> The PATCH response should not be limited to 204 -- there are many
> applications that might want to know whether fuzzy matching was
> used to apply the patch.  The spec should define that the response
> indicates what the server did.  An improvement would be to include
> any metadata in the response that was either modified or might
> indicate modification, but that is better done within the body of
> the response rather than mixing response metadata with that of the
> patched representation.

It's not limited to 204, that's just the "basic success code".  Many 
methods describe one or more success codes without limiting the 
implementation from using other success codes.

I could make the language more like RFC2616 in an attempt to define 
what the server did:

	  A successful response SHOULD use the 204 No Content status code, and
	      this response indicates that the server successfully applied the 
delta.
	  Note that 200 OK is not used in this case because 200 OK implies a 
body in the
	  response, and 201 Created is not used because the resource must 
already
	  exist.

If that doesn't capture it better I'll need specific text suggestions.

>
> Use of DELTAV status reporting is completely unnecessary.  The HTTP
> status code is more than capable of indicating the reason for failure,
> and explicit indication of what parts of the PATCH could not be
> applied will have to be specific to the supported diff format in
> any case.  A more reasonable mechanism would be to define a
> corresponding error format for each differencing format, since
> understanding of that format will be necessary for a user agent
> to explain what changes (not what parts of the diff file) have
> been rejected.  We can't define a universal XML response because
> most diffs cannot be enclosed within XML without additional
> encoding (such as base64), nor can we assume that line numbers
> are meaningful to binary differencing formats, though I suppose we
> could define a uniform way of counting the number of delta commands
> per format and uniformly indicate errors by reference to those
> numbers.

It is not necessary, but I wouldn't describe it as completely 
unnecessary.  It should be easy enough for the server to implement and 
for the client to use or ignore.  I disagree strongly that it would be 
"more reasonable" to define a corresponding error format for each 
differencing format.  I feel that the error codes given will be broadly 
useful for a number of differencing formats.

>
> Servers SHOULD NOT support the VCDIFF format until its IP restrictions
> are clarified and made available royalty-free for all uses of HTTP,
> at a minimum, and not just use within HTTP/1.1 as defined in 2001.

OK by me.  Easiest just not to mention VCDIFF.

>
> There is no reason for a server to advertise support for this
> method via OPTIONS *.  This is a resource-specific implementation
> question and does not need any more support from OPTIONS than
> is already provided for all methods.  Clients should never be
> encouraged to make global requests on a server for information
> that is resource-specific; servers don't work that way and all
> it does is recommend that the client waste bandwidth.

That's now a SHOULD, not a MUST -- but from others, are there any 
objections if I remove the description of OPTIONS * entirely?  Or 
should I say that "Allow-Patch" never appears in OPTIONS * responses?

Lisa

Received on Wednesday, 7 July 2004 21:16:48 UTC