Re: [APPS-REVIEW] review of draft-dusseault-http-patch-15

[Aaron Stone <aaron at serendipity.cx>]

Side note: looks like media types for text/unified-diff, text/context-diff
(or should those be application/vnd.gnu...), vcdiff (which has no media
type registered that I could find), etc., should be registered.

My open question:
What does one do with a patch document that describes actions on multiple
resources? Should we leave it assumed that this just doesn't make sense in
the HTTP context? Or does it make sense, if, say, the resource of the PATCH
method maps to a directory and the patch document applies to several files
within that directory? In that case, does anything need to be said about
the behavior of PATCH for this type of patch?


On Wed, 28 Oct 2009 19:00:38 +0100, Eliot Lear <lear at cisco.com> wrote:
> I have been selected as the Applications Area Review Team reviewer for 
> this draft (for background on apps-review, please see 
> http://www.apps.ietf.org/content/applications-area-review-team).
> 
> Please resolve these comments along with any other Last Call comments 
> you may receive. Please wait for direction from your document shepherd 
> or AD before posting a new version of the draft.
> 
> Document: draft-dusseault-http-patch-15
> Reviewer: Eliot Lear
> Review Date: October 28, 2009
> 
> Review Summary:
> 
> This draft is almost ready for publication as a Proposed Standard, but 
> should address the one major design issue below before proceeding.
> 
> Document Summary:
> 
> This document specifies an additional HTTP method, PATCH, which operates

> on a URI in a manner specific to document type.
> 
> Major Issues:
> 
> There is precisely one key design decision in this document that seems 
> to me at all controversial:
> Is media-type the appropriate key to determine the appropriate PATCH 
> method?  Is that level of indirection correct?  This immediately limits 
> the number of PATCH methods per media-type to one, and seems to me to 
> provide a difficult route to change the PATCH method.  For example, 
> suppose patch(1) became the standard for text/plain, and a new more 
> expressive diff/patch came along.  How would that be communicated 
> between client and server?  Let's assume for the moment that using a new

> media-type is not the best solution.

I found Section 3.2 to adequately describe which patch formats a server is
willing to accept for a given resource. The Accept-Patch header is defined
to allow multiple patch formats. A client might have to issue both HEAD and
OPTIONS to learn the media type of the document and the patch formats that
can be used, and you might have to add ETags to protect against a PUT
changing the resource type out from under you, etc. etc., but I don't think
the issue you raise exists.

3.2.  Example OPTIONS Request and Response

   [request]

   OPTIONS /example/buddies.xml HTTP/1.1
   Host: www.example.com

   [response]

   HTTP/1.1 200 OK
   Allow: GET, PUT, POST, OPTIONS, HEAD, DELETE, PATCH
   Accept-Patch: application/example, text/example

   The examples show a server that supports PATCH generally using two
   hypothetical patch document formats.

> Minor issues:
> 
> No matter how the authors answer the above question, I would suggest 
> that an additional IANA registry for PATCH methods be created.  The 
> structure of that registry, however, will depend on the answer to the
> above.
> 
> Nits:
> 
> Section 2, 3rd para, last sentence:
> 
>> i.e., new resources may be
>>     created, or existing ones modified, by the application of a PATCH
> 
> or removed?