Subject: Some comments on the PATCH draft

From: Andreas Sewe <[email-masked]>
Date: Tue, 03 Jul 2007 14:32:29 +0200

James Snell, the author of the recently revived PATH draft, has asked me
to resend my comments for further discussion to this list. (Originially
I send my comments to James only.)

So here they are:
> What bothers me currently about the PATCH draft is that it refers
> to resources throughout even though what is actually patched is a
> *representation* of a resource.
> 
> Besides being an issue of terminology this also has some
> implications when content negotiation is used. Granted, content
> negotiation complicates things quite a bit and might not be
> needed in most cases, but since PUT works fine even for
> negotiated resources I have the feeling that PATCH should work,
> too.
> 
> The problem with the draft is, however, that the content type of
> the entity send cannot be determined, since the Content-Type
> header contains (rightly so!) application/diff or some such type.
> But the assumption that the base media type is that of the
> resource is false as soon as that resource has many different
> representations. Which representation should the diff be applied
> to?
> 
> Representations might differ by Content-Type, Content-Language,
> etc., information which can be found in the Vary header. But
> besides Content-Type the other headers can be provided directly;
> only Content-Type carries the diff format's media type.
> 
> Unfortunately, I can't think of a clean solution of the top of my
> head; both adding a header like Patched-Type and requiring a
> media type parameter like application/diff;type="text/plain" seem
> clumsy to me. But if PUT works with content negotiation, so
> should PATCH!
> 
> Regards,
> 
> Andreas

---

From: Stefan Eissing <[email-masked]>
Date: Tue, 3 Jul 2007 15:06:15 +0200

It would make sense to advise against PATCH support for resources  
where the representation to be patched is not determined by the URI  
alone.

I think this is less of an issue than it sounds. In my experience,  
resources with content negotiation often have URIs for the different  
negotiated resources. Like apache which serves different languages on  
"/" but each language representation has its own URI.

Cheers,

Stefan

--
Stefan Eissing

<green/>bytes GmbH
Hafenweg 16
D-48155 Münster
Germany
Amtsgericht Münster: HRB5782

---

From: Yaron Goland <[email-masked]>
Date: Tue, 3 Jul 2007 14:02:31 -0700

But we can't really rely on that behavior. HTTP allows for content negotiation within a single URL, there is no obligation to provide different URLs for each type.

It seems like PATCH needs to distinguish between two different cases.

Content-type specific patch formats - For example Web3S has a format called Application/Web3SDelta+xml. This patch format only makes sense against resources that can be modeled with the Web3S infoset. So in this case the PATCH doesn't need to specify any particular content-type that is being 'patched' since the patch isn't occurring at the content-type level at all, it's occurring at an underlying resource modeling level.

Multi-content type patch format - Some patch formats can be used against anything that can be expressed as a binary stream. Other patch formats can be used against anything that can be expressed as a XML document. Etc. The point is that for these PATCH formats to work, in the case of resources that support multiple content types, there must be an explicit statement of what content-type representation the patch is intended to be applied to.

It seems like in the later case there should just be a specific header unique to PATCH whose semantics are "my generic patch format is meant to be applied against content-type X". While the header isn't sufficient to cover all negotiation possibilities for what a resource returns it would certainly seem to be necessary.

        Yaron

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]]
> On Behalf Of Stefan Eissing
> Sent: Tuesday, July 03, 2007 6:06 AM
> To: Andreas Sewe
> Cc: [email-masked]
> Subject: Re: Some comments on the PATCH draft
>
>

---

From: "Roy T. Fielding" <[email-masked]>
Date: Tue, 3 Jul 2007 15:47:21 -0700

>> representations. Which representation should the diff be applied

Negotiable content URIs don't normally support PUT either, for
good reasons.  Authoring should be done on source resources, not
resources that are derived from other sources.

>> clumsy to me. But if PUT works with content negotiation, so

PUT doesn't work with content negotiation.

The answer to your issue, though, is to use a diff format that
includes metadata about the target representation and the resulting
representation in the first chunk of the diff.  There are many
reasons to do that beyond the negotiation issue.

....Roy

---

From: Henrik Nordstrom <[email-masked]>
Date: Wed, 04 Jul 2007 14:56:23 +0200

> "/" but each language representation has its own URI.

And Content-Location advertises what this URI is.

Regards
Henrik

---

From: Andreas Sewe <[email-masked]>
Date: Thu, 05 Jul 2007 17:04:14 +0200

Roy T. Fielding wrote:
> Andreas Sewe wrote:

IMHO there's nothing in RFC 2616 that would prevent PUT from working
with negotiated resources.

Say, the resource <http://example.org/image> has both "application/gif"
and "application/png" representations. If I PUT an image of type
"application/png" at the above URL, the server has two options which
both satisfy the semantics of PUT:

# If the Request-URI refers to an already existing resource, the
# enclosed entity SHOULD be considered as a modified version of the one
# residing on the origin server.

1.) Discard the "application/gif" representation and consider, from now
    on, the "application/png" entity PUT as the sole, modified
    representation of <http://example.org/image>.
2.) Convert the "application/png" entity into a "application/gif"
    variant; both serve as modified representations of
    <http://example.org/image>.

Granted, if the two representations are available as source resources,
too, as advertised by Content-Location, modifying the source resources
directly is probably the better way. (Also, for resources which vary by
Content-Language option 2 is probably not an viable option.)

But there may be cases where the sources are not available at their own
URIs. When negotiating "text/plain" solely on Accept-Charset, e.g,
conversion could easily occur on the fly; there is no reason to provide
source resources for all the $n$ charsets out there.

So, what makes PUT inherently unsuitable for negotiated resources? I
don't see a compelling reason for it.

Regards,

Andreas

---

From: James M Snell <[email-masked]>
Date: Thu, 05 Jul 2007 12:27:51 -0700

After watching the conversation on this particular issue, I think the
only reliable solution is to add a statement like the following*:

   When a PATCH request is sent to a Request-URI that is capable of
   returning multiple alternate representations of a resource, the
   enclosed entity SHOULD contain sufficient information to allow the
   server to determine the representation to which the requested changes
   are to be applied.  If the server desires that the request be applied
   to a different URI, it MUST send a 301 (Moved Permanently) response;
   the user  agent MAY then make its own decision regarding whether or
   not to redirect the request.

In other words, the delta encoding** is responsible for identifying the
representation that is being modified.

* Note that some of this text was lifted from RFC2616
** or whatever we ultimately end up calling it

- James