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

From: Larry Masinter <[email-masked]>
Date: Tue, 18 May 2004 09:13:29 -0700

----Original Message-----
From: [email-masked] On Behalf Of [email-masked]
Sent: Monday, May 17, 2004 12:39 PM
To: [email-masked]
Subject: I-D ACTION:draft-dusseault-http-patch-02.txt

A New Internet-Draft is available from the on-line Internet-Drafts
directories.

	Title		: Partial Document Changes (PATCH Method) for HTTP
	Author(s)	: L. Dusseault
	Filename	: draft-dusseault-http-patch-02.txt
	Pages		: 13
	Date		: 2004-5-17
	
Several applications extending HTTP require a feature to do partial
resource modification.  Existing HTTP functionality only allows a
complete replacement of a document. This proposal adds a new HTTP
method, PATCH, to modify an existing HTTP resource.

A URL for this Internet-Draft is:
http://www.ietf.org/internet-drafts/draft-dusseault-http-patch-02.txt

...

---

From: Julian Reschke <[email-masked]>
Date: Fri, 21 May 2004 12:14:57 +0200

Comments on the latest draft:

 >    Note that byte ranges are already used in HTTP to do partial
 >    downloads (GET method).  However, they are not defined for uploads,
 >    and there are some missing pieces for uploads.  For example, the HTTP
 >    specification has no way for the server to send errors if the byte
 >    range in a PUT is invalid.  Byte ranges (or some other kind of range)

The server could always send a 4xx status code. Am I missing something?

 >    This standard defines the new method PATCH to alter a single existing
 >    resource, in place, by applying a delta or diff file.  The operation
 >    is atomic.  Note that WebDAV MOVE and COPY requests, if supported by
 >    the HTTP server, can be useful to rename or copy a different resource
 >    before applying PATCH.

I'm not sure how this is supposed to work. It may be an interesting 
feature, but to fully define it, the spec will need to say more about 
that topic (I personally feel that overloading COPY and/or MOVE with 
content modification operations would be a bad idea...).

 > 2.  Mechanisms
 >
 > 2.1  PATCH Method
 >
 >    The PATCH method requests that the request body (a patch document) be
 >    applied to the resource named in the Request-URI.  The resource named
 >    in the Request-URI MUST already exist (the server MUST NOT create a
 >    new resource with the body of the PATCH method).  The target

If one of the use cases for PATCH is creating sparse resources, it would 
make sense to allow PATCH to create new resources.

 >    The PATCH request MUST have a body.  It MUST include either the
 >    Content-Type header with a MIME type value indicating what the body
 >    type is, or an IM header as defined in RFC 3229 [4], to identify the
 >    delta format.  The IM header is only for gdiff and vcdiff, which are
 >    instance manipulations, and the Content-Type header is for delta
 >    formats which have registered MIME types.  Either way, the identified
 >    format MUST have the semantics of defining a change to an existing
 >    document (such as gdiff).

What if it has both?

 > 2.2  PATCH Response
 >
 > 2.2.1  Success Response
 >
 >    The basic success response code for PATCH is 204 No Content.  For
 >    this new method, 200 OK is not used because 200 OK implies a body in
 >    the response, and 201 Created is not used because the resource must
 >    already exist.
 >
 >    The server SHOULD provide a MD5 hash of the content after the delta
 >    was applied.  This allows the client to verify the success of the
 >    operation.  The PATCH method obviously MUST cause the ETag to change.
 >    So, if the server supports ETags, the server MUST return a strong
 >    ETag for use in future client operations.  If the server does not
 >    support strong ETags, then the server MUST return the Last-Modified
 >    header instead.

1. "if the server supports ETags" -> "if the server supports strong ETags".

2. I'd say that Last-Modified should be returned always.

3. Thought: there may be servers without good ETag support (for instance 
when using filesystem-based backends). If we require the server to 
compute MD5 checksums, we can also require it to check the MD5 of the 
given entity *before* the modification. In WebDAV speak, that would be a 
new state token for the "If" header; however for a spec that doesn't 
require WebDAV as base protocol, we may have to define a new request 
header, such as "If-Content-MD5-Match". This would make PATCH 
extra-safe, and we wouldn't need to worry ETag support.

 > 2.2.2  Error handling
 >
 >    This proposal uses the same mechanism as DeltaV to add much-needed
 >    info to base HTTP error responses.  Existing HTTP status codes are

(reference missing)

 >    not infinitely extensible but XML elements and namespaces are more
 >    so, and it's simple to treat the HTTP error code as a rough category
 >    and put detailed error codes in the body.
 >
 >    The PATCH method can return the following errors.  Please note that
 >    the notation "DAV:foobar" is merely short form for expressing "the
 >    'foobar' element in the 'DAV:' namespace".  It has meaning only in
 >    English, not on the wire.  Also note that the string error codes are
 >    not meant to be displayed but instead as machine parsable known error
 >    codes (thus there is no language code).

I think this spec shouldn't use the "DAV:" namespace. Also, if this spec 
adopts RFC3253-style error handling, it should stay consistent with 
RFC3253 (in RFC3253, the names identify *conditions*, not *errors*; thus 
the individual codes need to be reversed, such as 
"delta-format-supported" instead of "delta-format-unsupported").

 >    DAV:delta-format-unsupported: Used with 501 Not Supported status
 >       code.  Returned by the server when it doesn't support the delta
 >       format chosen by the client.

I don't think we want 501 here:

"The server does not support the functionality required to fulfill the 
request. This is the appropriate response when the server does not 
recognize the request method and is not capable of supporting it for any 
resource." <http://greenbytes.de/tech/webdav/rfc2616.html#status.501>

 >    DAV:delta-format-badly-formatted: Used with 400 Bad Request when the
 >       server finds that the delta document provided by the client was
 >       badly formatted and non-compliant.

Suggestion: be more precise about what "badly formatted" means.

 > 2.3  Delta Formats
 >
 >    A set of changes for a resource is itself a document, called a change
 >    document or delta.  The delta format is uniquely identified through

Make it a definition; and use the same term (I'd prefer "delta 
document") everywhere.

a
 >    MIME type.  Servers advertise supported delta mechanisms by
 >    advertising these MIME types, and clients specify which one they're
 >    using by including the MIME type in the Content-Type header of the
 >    PATCH request.

What about the "IM" header?

 >
 >    The VCDIFF [5] format identifier is "vcdiff".  The GDIFF [6] format
 >    identifier is "gdiff".  Servers SHOULD support VCDIFF for all static
 >    resources.

What's the relation of the aforementioned identifiers and the MIME type? 
And what is a "static" resource?

 > 2.4  Advertising Support in OPTIONS
 >
 >    The server advertises its support for the features described here
 >    with OPTIONS response headers.  The "Allow" OPTIONS header is already
 >    defined in HTTP 1.1  to contain all the allowable methods on the
 >    addressed resource, so it's natural to add PATCH.

Indeed.  In fact this is so obvious that I think it shouldn't be said at 
all.

 >    OPTIONS * presents a bit of a special case, as it does not address a
 >    resource, and does not always show all the server's features.  In
 >    responses to OPTIONS *, a server supporting this specification SHOULD
 >    include the PATCH method in the "Allow" header and SHOULD show the
 >    union of all supported diff methods in the "Accept-Patch" header.

This SHOULD level requirement in general can not be implemented using 
the Java servlet API; it's also very unclear how it actually helps the 
client in any way, as the supported delta formats may vary across 
resources. Please explain the rational.

 >    Example: OPTIONS request and response for specific resource
 >
 >
 >        [request]
 >
 >        OPTIONS /example/buddies.xml HTTP/1.1
 >        Host: www.example.com
 >
 >        [response]
 >
 >        HTTP/1.1 200 OK
 >        Allow: GET, PUT, POST, OPTIONS, HEAD, TRACE, DELETE, PATCH
 >        Accept-Patch: example/xcap+xml

Shouldn't "vcdiff" appear here?

 >    [6]  van Hoff, A. and J. Payne, "Generic Diff Format Specification",
 >         August 1997.

URL?

Best regards, Julian

-- 
<green/>bytes GmbH -- http://www.greenbytes.de -- tel:+492512807760

---

From: Jamie Lokier <[email-masked]>
Date: Fri, 21 May 2004 13:05:51 +0100

Julian Reschke wrote:
> 1. 2. 3.

4. The PATCH method won't cause the ETag to change if the patched
entity is identical to the one before patching.

> resources. Please explain the rational.

It also cannot be implemented in general over reverse-proxies which
forward requests to different servers depending on the URL.

-- Jamie

---

From: Alex Rousskov <[email-masked]>
Date: Fri, 21 May 2004 07:35:44 -0600 (MDT)

> entity is identical to the one before patching.

Whether the ETag changes depends on whether it reflects things other
than raw octet composition. For example, if ETag reflects last "write
access" time, it may change even if octets remain the same.

Alex.

---

From: Jamie Lokier <[email-masked]>
Date: Fri, 21 May 2004 15:00:39 +0100

> access" time, it may change even if octets remain the same.

I should have said "the PATCH method *needn't* cause the ETag to change".

The ETag may reflect the Last-Modified time, which needn't change if
the content and entity headers aren't changed by the patch.  It's a
matter of server policy.  I think at least some unix servers won't
alter the mtime of a file if you open it for writing but don't write
anything - as some patch operations conceivably might do.

Also, even if the server definitely does recording the time of the
patch as the last write access time, and uses that as part of the
ETag, the time used for the Etag usually has a granularity (often 1
second).  So it might still not change the ETag.

If a server is only using the POSIX mtime field for an ETag then it
should probably not call it a strong ETag.  However if it uses mtime
and also the a strong checksum of the file to construct the ETag then
that's a fine strong ETag - which needn't change as a result of PATCH.

-- Jamie

---

From: Lisa Dusseault <[email-masked]>
Date: Fri, 21 May 2004 12:46:48 -0700

> The server could always send a 4xx status code. Am I missing something?

Yes, the server could, but HTTP doesn't define this as a way to respond 
to partial upload requests, so clients might find it hard to 
interoperate well.  Anyway I think it's moot, unless we decide to 
design a partial upload request standard based around byte-range 
headers -- I think sending a diff is far preferable since diff formats 
are already well understood, used in HTTP, and more powerful.

> content modification operations would be a bad idea...).

This is just pointing out that COPY and MOVE are useful -- this doesn't 
overload them or even explain how this works.  COPY and MOVE are fully 
defined in RFC2518 and are independent from PATCH.  The reason these 
are mentioned, is because somebody asked if PATCH could be used to get 
the source from one URL, but place the result in another URL -- and 
COPY or MOVE combined with PATCH can achieve nearly the same thing 
without any new specification required.  I will however try to make the 
text a little clearer in that MOVE and COPY can be used as is, 
independently of the PATCH proposal, to rename or copy an entity before 
applying PATCH to it.

> If one of the use cases for PATCH is creating sparse resources, it 
> would make sense to allow PATCH to create new resources.

I can't think of any benefit over using PUT.  It only makes PATCH more 
complicated to define how it acts on new resources.  Note that the 
client is perfectly capable of using PUT to create an empty resource, 
and diff formats are perfectly capable of applying a diff to an empty 
resource -- but I would think that generally clients would prefer to 
PUT at least a significant chunk of the resource content when creating 
the resource.

> >    document (such as gdiff).

I'll address this, thanks.

> 1. "if the server supports ETags" -> "if the server supports strong 

OK

> 2. I'd say that Last-Modified should be returned always.

OK -- there are a few Web servers that don't keep a last-modified date 
at all, but I can at least make this a SHOULD.

>
> 3. Thought: there may be servers without good ETag support (for 
> instance when using filesystem-based backends). If we require the 
> server to compute MD5 checksums, we can also require it to check the 
> MD5 of the given entity *before* the modification. In WebDAV speak, 
> that would be a new state token for the "If" header; however for a 
> spec that doesn't require WebDAV as base protocol, we may have to 
> define a new request header, such as "If-Content-MD5-Match". This 
> would make PATCH extra-safe, and we wouldn't need to worry ETag 
> support.

This would be a great extension in general, completely independent of 
PATCH, and I would support such an extension.

> >    info to base HTTP error responses.  Existing HTTP status codes are

HTTP reference appears in the Introduction.  I added a DeltaV reference 
to the introduction as well, where DeltaV is first mentioned.  I don't 
know how I overlooked that!

> I think this spec shouldn't use the "DAV:" namespace. Also, if this 
> spec adopts RFC3253-style error handling, it should stay consistent 
> with RFC3253 (in RFC3253, the names identify *conditions*, not 
> *errors*; thus the individual codes need to be reversed, such as 

I suppose we could define a new namespace just for PATCH; but you're 
the only one who's mentioned this so I don't think it's likely to be 
much of a problem.  Since error codes are simply identifying strings, I 
see no problem with using identifying strings which make sense to the 
reader/developer/debugger.

> recognize the request method and is not capable of supporting it for 
> any resource." 
> <http://greenbytes.de/tech/webdav/rfc2616.html#status.501>

OK, that's a fine point, we can use something else.  I wish 501 
Unsupported were less specific though!

> Suggestion: be more precise about what "badly formatted" means.

OK.

> Make it a definition; and use the same term (I'd prefer "delta 

A matter of readability; I think the draft is already pretty readable 
here, because we're not defining any special meaning for the word, it's 
already well used in other context.

> What about the "IM" header?

Good catch.  I'll fix that.

> What's the relation of the aforementioned identifiers and the MIME 
> type? And what is a "static" resource?

Clarified.  I'll change "static" to "resources with static content, 
that is, content that is not generated dynamically."  This brings the 
text in line with the wording used in RFC2616.

> Indeed.  In fact this is so obvious that I think it shouldn't be said 
> at all.

Yeah -- a lot of the things you've asked for clarifications in this 
email are "obvious" to other people!  Obvious is *definitely* in the 
eye of the beholder.  This clarification/explanation is in there 
because of previous discussions where this obviously wasn't "obvious" 
to everybody (including, I think, me.)

> resources. Please explain the rational.

The rationale for putting this in is that a lot of servers *do* 
indicate server features in the responses to OPTIONS *.  This helps the 
client because it indicates they can probably cache the feature support 
information and may not need to do OPTIONS on every resource.  Some 
clients do make OPTIONS * requests.

It's not a MUST because as you point out, some servers cannot do this.  
This tension between the desirability of OPTIONS * and the 
infeasibility of it is a tension that I do not intend to resolve in 
this specification.

> Shouldn't "vcdiff" appear here?

I'm of two minds about this.  It might be undesirable for servers to 
support 'vcdiff' if they support something that's better in this 
particular circumstance.  I guess it's better for the example to show 
what you'd see if the server followed every SHOULD.

> >    [6]  van Hoff, A. and J. Payne, "Generic Diff Format 

It's funny -- it's in the XML source, but the generator didn't see fit 
to put the URL in the text output.  I guess that URLs are just not 
required in the text version.

> Best regards, Julian

Thanks for the review.

Lisa

---

From: Lisa Dusseault <[email-masked]>
Date: Fri, 21 May 2004 12:50:53 -0700

> entity is identical to the one before patching.

Fixed.

> forward requests to different servers depending on the URL.
OPTIONS * is a difficult problem; I don't really have a solution to it, 
nor do I know of any consensus on "the right thing" to do about it.  
The requirement is only a SHOULD, since obviously some implementations 
can't do this.

---

From: Julian Reschke <[email-masked]>
Date: Fri, 21 May 2004 22:04:50 +0200

Lisa Dusseault wrote:

> nor do I know of any consensus on "the right thing" to do about it.  The 
> requirement is only a SHOULD, since obviously some implementations can't 
> do this.

I think it's understood that under many cirumstances, "OPTIONS *" will 
simply not work. Making it a "SHOULD" requirement suggests to clients 
that they reasonably can expect it to work most of the time; however the 
*opposite* is true.

Clients can not rely on "OPTIONS *" working as described, and it's also 
not clear what the value of this feature is. The client can't rely on 
PATCH being available on every resource, nor can it rely on specific 
delta formats being supported on all resources.

As such, it should be a "MAY", or even better, the description should be 
removed altogether.

If you disagree, I'd be interested to hear about a use case where the 
response from "OPTIONS *" will indeed help the client in any way.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Fri, 21 May 2004 22:28:39 +0200

Lisa Dusseault wrote:

> interoperate well.  Anyway I think it's moot, unless we decide to design 

Sorry? Clients must expect a 4xx status code for every conceivable HTTP 
method.

> a partial upload request standard based around byte-range headers -- I 
> think sending a diff is far preferable since diff formats are already 
> well understood, used in HTTP, and more powerful.

Yes, but that wasn't the question. This is the rationale for defining a 
new method, and this particular given reason just is incorrect (at least 
I'm not understanding it). In doubt, just remove the statement.

> defined in RFC2518 and are independent from PATCH.  The reason these are 
> mentioned, is because somebody asked if PATCH could be used to get the 
> source from one URL, but place the result in another URL -- and COPY or 
> MOVE combined with PATCH can achieve nearly the same thing without any 
> new specification required.  I will however try to make the text a 
> little clearer in that MOVE and COPY can be used as is, independently of 
> the PATCH proposal, to rename or copy an entity before applying PATCH to 
> it.

OK. I had the impression that you were planning to roll PATCH semantics 
into specific COPY/MOBE operations.

> I can't think of any benefit over using PUT.  It only makes PATCH more 

Creating sparse resources...

> resource -- but I would think that generally clients would prefer to PUT 
> at least a significant chunk of the resource content when creating the 
> resource.

Agreed, that can be simulated by PUT (empty body) / then PATCH. In 
doubt, the spec should specify the simpler approach, though. I'm not 
sure that forbidding PATCH to unmapped URLs is indeed simpler...

>> would make PATCH extra-safe, and we wouldn't need to worry ETag support.
> 
> 

So should this be part of the PATCH spec?

> I suppose we could define a new namespace just for PATCH; but you're the 
> only one who's mentioned this so I don't think it's likely to be much of 
> a problem.  Since error codes are simply identifying strings, I see no 
> problem with using identifying strings which make sense to the 

Could you please address the issue of this spec being inconsistent with 
RFC3253? *If* PATCH borrows mechanisms from RFC3253 (which I think is A 
Good Thing), it definitively should do that in a consistent way. If, as 
you say, it doesn't matter as we're only talking about identifiers for 
machine consumption, it's even less clear why you're changing the format 
here.

> already well used in other context.

Well, the spec text *sounds* as you're defining something here. I think 
it would make sense just to use *one* term and to stick with it.

> Clarified.  I'll change "static" to "resources with static content, that 
> is, content that is not generated dynamically."  This brings the text in 
> line with the wording used in RFC2616.

I can't find the term "static" in RFC2616... It's also not clear how 
"generated dynamically" affects the ability to use a specific PATCH 
format. Assuming that PATCH will only work for authorable resources 
(those you can PUT to), could you please explain which of the set of 
these resources you're trying to exclude?

> what you'd see if the server followed every SHOULD.

Certainly. If you don't mean "SHOULD", don't make it a "SHOULD".

> required in the text version.

Depends on how you put it into the XML source. If you send me the XML 
version (or just the reference), I'll figure out how to fix that.

Best regards, Julian

---

From: Lisa Dusseault <[email-masked]>
Date: Fri, 21 May 2004 13:41:24 -0700

> these resources you're trying to exclude?

That's an even better wording -- authorable resources, or those you can 
PUT to.  Thanks for providing specific wording.

Lisa

---

From: Lisa Dusseault <[email-masked]>
Date: Fri, 21 May 2004 13:45:49 -0700

I'd like to see wider input before diverging from what I see as pretty 
standard practice.  Is OPTIONS * dead?  Is it useful?  Both?

I had always seen OPTIONS * to be very useful.  At Xythos, we went to a 
deal of effort to make it work even though the Xythos WFS was a java 
servlet-based technology.  Xythos WFS worked with clients that expected 
to find useful information in OPTIONS *, including the Xythos WFC 
(before that, Teamstream behaved the same way, I think).  The clients 
looked for features advertised in OPTIONS *, so that the client would 
know whether it would be worthwhile querying individual resources for 
further detail on supported features.

Some clients, like Microsoft clients, use OPTIONS '/', which can be 
just as hard or harder for the server to support than OPTIONS *.  And 
if the server doesn't advertise a major feature in OPTIONS * or OPTIONS 
/, then the client doesn't bother looking for the feature on individual 
URLs -- it's probably too prohibitive to do that roundtrip on every 
resource visited.  I think that a server implemented today that didn't 
put features in OPTIONS * or OPTIONS / would find that some clients 
failed to enable features that would otherwise be enabled.  This may be 
most true for WebDAV features like locking.

I'm now in the position of developing a WebDAV client from the ground 
up, rather than a server, as I've done before.  I assure you that the 
client would rather have some indication (in OPTIONS * or OPTIONS / or 
elsewhere) that a feature might be supported somewhere in the 
repository.  This is so that a GUI can show a button as enabled or 
disabled right away, as the client navigates through a bunch of 
resources.  For example, the "lock" button should be visible on the 
toolbar when the user is navigating a repository that might support 
locking somewhere -- but the "lock" button should be at least greyed 
out, if not absent, when the user is navigating a repository that 
doesn't support locking at all.

Developers hate uncertainty, but users are generally better at dealing 
with it than we think they are.  It's a principle of good user 
interface to show affordances for things that might be possible.  It's 
OK if the affordance doesn't work once in a while -- it's better than 
the user not to be allowed, or not to know, that they can even do the 
function in the first place.  That's why I think it's good for OPTIONS 
* to show that a feature like locking is available somewhere in the 
repository, even if it's not available everywhere.

Perhaps the solution is to fix the tools.  Java Servlets could easily 
have been designed to make OPTIONS * aggregate information from a 
number of servlets.  Reverse proxies could send OPTIONS * requests to 
the different servers and bundle the answers together, if the set is 
finite and known.  Or we could provide some way of responding to 
OPTIONS * with a specific advertised caveat that "this response does 
not have the list of features available in the repository(ies) that can 
be addressed at this server".

In any case, this issue affects PATCH no more than it affects any other 
HTTP extension.

Lisa

On May 21, 2004, at 1:04 PM, Julian Reschke wrote:

>> OPTIONS * is a difficult problem; I don't really have a solution to 
>> it, nor do I know of any consensus on "the right thing" to do about 
>> it.  The requirement is only a SHOULD, since obviously some 
>> implementations can't do this.
>
> that they reasonably can expect it to work most of the time; however 
> the *opposite* is true.
>
> Clients can not rely on "OPTIONS *" working as described, and it's 
> also not clear what the value of this feature is. The client can't 
> rely on PATCH being available on every resource, nor can it rely on 
> specific delta formats being supported on all resources.
>
> As such, it should be a "MAY", or even better, the description should 
> be removed altogether.
>

---

From: Julian Reschke <[email-masked]>
Date: Fri, 21 May 2004 22:55:54 +0200

> PUT to.  Thanks for providing specific wording.

OK. But then this makes it "Servers SHOULD support VCDIFF on all 
resources where PATCH is allowed", right?

Julian

---

From: Lisa Dusseault <[email-masked]>
Date: Fri, 21 May 2004 14:01:55 -0700

Heh.  Effectively, yes.

On May 21, 2004, at 1:55 PM, Julian Reschke wrote:

>> That's an even better wording -- authorable resources, or those you 
>> can PUT to.  Thanks for providing specific wording.
>

---

From: Julian Reschke <[email-masked]>
Date: Fri, 21 May 2004 23:08:58 +0200

> standard practice.  Is OPTIONS * dead?  Is it useful?  Both?

It can't be both. As far as I'm concerned it doesn't work (or at least 
it doesn't do what you're asking it for).

> further detail on supported features.

I've been working on both WebDAV server and client informations for over 
three years now, and I haven't *seen* any client making that request 
(and if some clients *did* make that request, they obviously proceeded 
without that information ok; otherwise I'd definitively had gotten 
customer complaints).

> Some clients, like Microsoft clients, use OPTIONS '/', which can be just 
> as hard or harder for the server to support than OPTIONS *.  And if the 

That's a known bug in older Microsoft clients; it has been fixed for a 
long time.

> server doesn't advertise a major feature in OPTIONS * or OPTIONS /, then 
> the client doesn't bother looking for the feature on individual URLs -- 
> it's probably too prohibitive to do that roundtrip on every resource 
> visited.  I think that a server implemented today that didn't put 
> features in OPTIONS * or OPTIONS / would find that some clients failed 
> to enable features that would otherwise be enabled.  This may be most 
> true for WebDAV features like locking.

I'm not aware of any such client except for the Microsoft Windows XP 
WebDAV Mini-Redirector (which does OPTIONS /), and in that case 
Microsoft has indeed acknowledged that this is a client bug: 
<http://support.microsoft.com/?kbid=831805>.

Besides, can we please distinguish between "*" and "/"? They are *very* 
different? "OPTIONS /" returns communication options for the root URL, 
this is well-defined and will work with any compliant server.

> doesn't support locking at all.

Support for locking will vary across resources; this particular piece of 
information can better be obtained by using the "DAV:" header on the 
collection you're looking at 
(<http://greenbytes.de/tech/webdav/rfc2518.html#HEADER_DAV>).

BTW: so what will you do when the server does *not* support "OPTIONS *"?

> with it than we think they are.  It's a principle of good user interface 
> to show affordances for things that might be possible.  It's OK if the 
> affordance doesn't work once in a while -- it's better than the user not 
> to be allowed, or not to know, that they can even do the function in the 
> first place.  That's why I think it's good for OPTIONS * to show that a 
> feature like locking is available somewhere in the repository, even if 
> it's not available everywhere.

So exactly what do you do when the Allow header upon "OPTIONS *" doesn't 
contain LOCK? Enable or disable that button?

> have been designed to make OPTIONS * aggregate information from a number 
> of servlets.  Reverse proxies could send OPTIONS * requests to the 
> different servers and bundle the answers together, if the set is finite 
> and known.  Or we could provide some way of responding to OPTIONS * with 
> a specific advertised caveat that "this response does not have the list 
> of features available in the repository(ies) that can be addressed at 
> this server".
> 

That's correct; however other specifications are simply silent about 
that topic, while the current text for PATCH makes the impression that 
this is a feature that's going to work in some reliable fashion. This is 
simply incorrect.

Regards, Julian

---

From: "Roy T. Fielding" <[email-masked]>
Date: Fri, 21 May 2004 15:45:21 -0700

> 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 of reinterpreting the meaning of the existing
error messages in HTTP that tell the client when a type is not
supported.  This is not the same problem as addressed in delta
encoding (i.e., server push replication) and does not need IM
as a solution.  Failure to define vcdiff and gdiff in the media type
registry is no excuse for adding complexity to HTTP.  I would
rather see the specification define "application/vcdiff" and
"application/gdiff" in the appendices, which it is certainly
capable of doing on behalf of the IETF, rather than allow media
type registration exemptions just because the owners had no
need for those types.

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

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.

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

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.

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.

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.

Aside from what is noted above, I do think that PATCH should be
a standard part of HTTP and needs an appropriate specification.

Cheers,

Roy T. Fielding                            <http://roy.gbiv.com/>
Chief Scientist, Day Software              <http://www.day.com/>