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

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

Received on Friday, 21 May 2004 06:15:31 UTC