Subject: Content-Location, was: PATCH draft

From: Julian Reschke <[email-masked]>
Date: Mon, 02 Feb 2009 10:24:58 +0100

Roy T. Fielding wrote:
> 
> I think my earlier comments still hold: 209 is not needed anywhere
> because that functionality is already covered by Content-Location.
>  
> ....Roy
> ...

1) If we can simplfy the PATCH spec further, then yes, we should do that.

2) I was just looking at the description of Content-Location:

"The Content-Location entity-header field MAY be used to supply the 
resource location for the entity enclosed in the message when that 
entity is accessible from a location separate from the requested 
resource's URI..." -- 
<http://greenbytes.de/tech/webdav/rfc2616.html#rfc.section.14.14>)

 From that description, it's not entirely clear that it applies to this 
sue case, as the location returned in Content-Location would *not* be 
separate from the resource's URI. I guess we'll have to tune the 
language here somewhat.

BR, Julian

---

From: Julian Reschke <[email-masked]>
Date: Mon, 02 Feb 2009 21:51:09 +0100

Lisa Dusseault wrote:
>> Section 2., paragraph 4:
>> OLD:
>>
>>   If the request passes through a cache and the Request-URI identifies
>>   one or more currently cached entities, those entries SHOULD be
>>   treated as stale.  Responses to this method are not cacheable, unless
>>   the response includes appropriate Cache-Control or Expires header
>>   fields or the response uses the 209 Content Returned status code as
>>   defined in Section 4.  The 303 (See Other) response can be used to
>>   direct the user agent to retrieve a cacheable resource.
>>
>> NEW:
>>
>>   If the request passes through a cache and the Request-URI identifies
>>   one or more currently cached entities, those entries SHOULD be
>>   treated as stale.  Responses to this method are not cacheable, unless
>>   the response includes appropriate Cache-Control or Expires header
>>   fields or the response uses the 209 Content Returned status code as
>>   defined in Section 4.  The 303 (See Other) response can be used to
>>   direct the user agent to retrieve a cacheable resource. [[anchor1:
>>   ???]]
>>
>> I'm not totally sure why we'd want 303 here. What's wrong with 200; 
>> it's not like the 303 ever would include a different URI in the 
>> Location header, right?
> 
> Right, but the 303 would direct the client to do a GET request to 
> presumably the same resource, which would then trigger caches to update 
> their copies -- even if the cache were oblivious to the meaning of PATCH.
> 
> I have no objection too keeping in 303 or taking it out, but I want to 
> make sure we remember why it was added before we flip-flop again.  
> Julian, let me know.

This seems to target the same use case as 209 and Content-Location (as 
proposed by Roy).

We really should converge on a single solution, so if we can make 
Content-Location work (potentially with an example in the PATCH spec amd 
an improvement in HTTPbis), that would be best.

> ...
>> Why exactly do we require a strong etag here in general?
> 
> This spec text doesn't require strong ETags to be used by the server.  
> It sidesteps the issue that we have no clue what a weak ETag would mean 
> and how a client could reasonably use it -- it just says what the client 
> can do if it gets a strong one.  Your proposed text could lead clients 
> very astray if a weak ETag was used as defined in RFC2616, and a PATCH 
> was applied to a document that has slight changes from what the client 
> thought it would be.

But it's the server that mints the etags (decided on strong vs weak), 
and also which implements a specific PATCH format. Thus, it seems, it's 
best to let the server decide whether it can execute a given conditional 
request.

 >...
>> I think in all these cases 422 is not the right choice, because the 
>> problem is not with the request, but the state of the resource.  Thus 
>> it seems 409 Conflict would be better.
> 
> What's wrong with 422?  It doesn't say that there's a problem with the 
> request necessarily, in fact the description says "this error condition 
> may occur if an XML request body contains ... semantically erroneous XML 
> instructions".

Yes, that is the request, isn't it? :-)

> It's unclear from the part of the text you quoted, do you think all of 
> the cases in the document are bad for 422 or just the 3 points you quoted?

Sorry, that was a result of rfcdiff being confused, and myself 
selectively pasting stuff into the mail.

Let's see:

>     * The client attempted to apply a patch document to an empty or non-existent resource, but the patch document chosen cannot be applied to an empty or non-existent resource.

I'd say that's 409 or 404.

>     * The client attempted to apply a structural modification and the structures assumed to exist did not exist (e.g. a patch which specifies changing element 'foo' to element 'bar' but element 'foo' doesn't exist).

My choice would be 409 (Conflict -- the current state of the resource 
doesn't allow the request to succeed)

>     * The client attempted to modify a resource in a way that would cause the resource to become invalid. For instance, a modification to a well-formed XML document that would cause it to no longer be well-formed.

No proposal for this one; a 422 might be ok here if the request will 
always fail, no matter what state the resource is in.

>     * The client attempted to modify a resource that has multiple representations but the server was unable to choose which representation to modify.

This would be content negotiation for write operations. This doesn't 
seem to work for PUT in the real world, so I wouldn't even mention it 
for PATCH (that is, always apply PATCH to a more specific URI, as 
returned in GET/HEAD's Content-Location).

> Do you think the 422 response is useful for anything in PATCH?

Maybe one of these cases (see above).

BR, Julian

---

From: Lisa Dusseault <[email-masked]>
Date: Mon, 02 Feb 2009 20:36:31 +0000

I'm applying most of these fixes, but have some questions.

Right, but the 303 would direct the client to do a GET request to  
presumably the same resource, which would then trigger caches to  
update their copies -- even if the cache were oblivious to the meaning  
of PATCH.

If we keep it, I suggest we expand the sentence: "The 303 (See Other)  
response can be used to direct the user agent to retrieve a cacheable  
resource with a new GET request, which will have the side effect of  
updating caches along the path."

>
> Section 2., paragraph 5:
> OLD:
>
>   Collisions from multiple requests are more dangerous than PUT
>   collisions, because a patch document that is not operating from a
>   known base point may corrupt the resource.  Clients wishing to apply
>   a patch document to a known entity can first acquire the strong ETag
>   of the resource to be modified, and use that Etag in the If-Match
>   header on the PATCH request to verify that the resource is still
>   unchanged.  If a strong ETag is not available for a given resource,
>   the client can use If-Unmodified-Since as a less-reliable safeguard.
>
> NEW:
>
>   Collisions from multiple requests are more dangerous than PUT
>   collisions, because a patch document that is not operating from a
>   known base point may corrupt the resource.  Clients wishing to apply
>   a patch document to a known entity can first acquire the ETag of the
>   resource to be modified, and use that Etag in the If-Match header on
>   the PATCH request to verify that the resource is still unchanged.   
> If
>   an ETag is not available for a given resource, the client can use  
> If-
>   Unmodified-Since as a less-reliable safeguard.
>

This spec text doesn't require strong ETags to be used by the server.   
It sidesteps the issue that we have no clue what a weak ETag would  
mean and how a client could reasonably use it -- it just says what the  
client can do if it gets a strong one.  Your proposed text could lead  
clients very astray if a weak ETag was used as defined in RFC2616, and  
a PATCH was applied to a document that has slight changes from what  
the client thought it would be.

>
>
> Section 2.2., paragraph 3:
> OLD:
>
>      *  The client attempted to apply a structural modification and  
> the
>         structures assumed to exist did not exist (e.g. a patch which
>         specifies changing element 'foo' to element 'bar' but element
>         'foo' doesn't exist).
>      *  The client attempted to modify a resource in a way that would
>         cause the resource to become invalid.  For instance, a
>         modification to a well-formed XML document that would cause it
>         to no longer be well-formed.
>      *  The client attempted to modify a resource that has multiple
>         representations but the server was unable to choose which
>         representation to modify.
>   Conflicting modification:  Specified with a 412 (Precondition  
> Failed)
>      when a client uses either the If-Match or If-Unmodified-Since
>      request headers and attempts to apply a patch document to a
>      resource whose state has changed since the patch was created.  If
>      the server detects a possible conflicting modification and  
> neither
>      the If-Match or If-Unmodified-Since request headers are used, the
>      server can return a 409 (Conflict) response.
>   Concurrent modification:  When a server receives multiple concurrent
>      requests to modify a resource, those requests SHOULD be queued  
> and
>      processed in the order in which they are received.  If a server  
> is
>      incapable of queuing concurrent requests, all subsequent requests
>      SHOULD be rejected with a 409 (Conflict) until the first
>      modification request is complete.
>
> problem is not with the request, but the state of the resource.   
> Thus it seems 409 Conflict would be better.

What's wrong with 422?  It doesn't say that there's a problem with the  
request necessarily, in fact the description says "this error  
condition may occur if an XML request body contains ... semantically  
erroneous XML instructions".

It's unclear from the part of the text you quoted, do you think all of  
the cases in the document are bad for 422 or just the 3 points you  
quoted?

Thanks,
Lisa

--- Scanned by M+ Guardian Messaging Firewall ---
Messaging Architects sponsors The Spamhaus Project.

---

From: Julian Reschke <[email-masked]>
Date: Wed, 04 Feb 2009 13:30:31 +0100

> best to let the server decide whether it can execute a given conditional 

...adding an example:

Consider a server that uses an XML database as backing store, which thus 
uses weak etags because it can't guarantee to preserve the ordering of 
attribute values. That server wouldn't be able to support a binary patch 
format (as in "set octet x to y"), but it could support a patch format 
that is based on the XML Infoset ("insert element <foo> after the node 
selected by XPath..."), even for weak etags.

That's why I think the server should have the last word on this.

BR, Julian

---

From: Lisa Dusseault <[email-masked]>
Date: Wed, 04 Feb 2009 18:04:47 +0000

Sure.  But the client code I sent would break that server's model.   
There's nowhere in the spec that says that you can compare a weak ETag  
to a strong ETag by stripping the "W/".

Lisa

On Feb 4, 2009, at 4:30 AM, Julian Reschke wrote:

> Julian Reschke wrote:
>> ...
>>> This spec text doesn't require strong ETags to be used by the  
>>> server.  It sidesteps the issue that we have no clue what a weak  
>>> ETag would mean and how a client could reasonably use it -- it  
>>> just says what the client can do if it gets a strong one.  Your  
>>> proposed text could lead clients very astray if a weak ETag was  
>>> used as defined in RFC2616, and a PATCH was applied to a document  
>>> that has slight changes from what the client thought it would be.
>> But it's the server that mints the etags (decided on strong vs  
>> weak), and also which implements a specific PATCH format. Thus, it  
>> seems, it's best to let the server decide whether it can execute a  
>> given conditional request.
>> ...
>
> ...adding an example:
>
> Consider a server that uses an XML database as backing store, which  
> thus uses weak etags because it can't guarantee to preserve the  
> ordering of attribute values. That server wouldn't be able to  
> support a binary patch format (as in "set octet x to y"), but it  
> could support a patch format that is based on the XML Infoset  
> ("insert element <foo> after the node selected by XPath..."), even  
> for weak etags.
>

---

From: Julian Reschke <[email-masked]>
Date: Wed, 04 Feb 2009 19:22:04 +0100

> Sure.  But the client code I sent would break that server's model.

You mean this one...?

>         etag.weak = (value[:2] == "W/")
>        
>         if etag.weak:
>             etag.tag = value[2:]
>         else:
>             etag.tag = value

That's hard to tell unless we know what the client is going to do with it.

> to a strong ETag by stripping the "W/".

Well, a client can do that, but in general it's not going to have the 
desired effect.

I'm not sure what your point is... That there are servers and clients 
out there which are broken with respect to weak etag handling? I agree 
with that, but I do not agree that this means the PATCH spec should rule 
out their use.

BR, Julian

PS: And, btw, httpbis currently *does* define that W/"foo" and "foo" 
match weakly; see 
<http://greenbytes.de/tech/webdav/draft-ietf-httpbis-p4-conditional-05.html#rfc.section.5> 
and <http://trac.tools.ietf.org/wg/httpbis/trac/ticket/71>.

BR, Julian

---

From: David Morris <[email-masked]>
Date: Wed, 4 Feb 2009 11:02:14 -0800 (PST)

On Wed, 4 Feb 2009, Julian Reschke wrote:

>> There's nowhere in the spec that says that you can compare a weak ETag to a 
>> strong ETag by stripping the "W/".
>
> Well, a client can do that, but in general it's not going to have the desired 
> effect.
>
> I'm not sure what your point is... That there are servers and clients out 
> there which are broken with respect to weak etag handling? I agree with that, 
> but I do not agree that this means the PATCH spec should rule out their use.
>
> BR, Julian
>
> PS: And, btw, httpbis currently *does* define that W/"foo" and "foo" match 
> weakly; see 

Which just might be why that code fragment parses off the W/ and remembers 
it with the etag.weak boolean.

---

From: Lisa Dusseault <[email-masked]>
Date: Wed, 04 Feb 2009 18:34:42 +0000

On Feb 4, 2009, at 10:22 AM, Julian Reschke wrote:
>
> I'm not sure what your point is... That there are servers and  
> clients out there which are broken with respect to weak etag  
> handling? I agree with that, but I do not agree that this means the  
> PATCH spec should rule out their use.

Nothing to do with PATCH -- I got my threads crossed.

> match weakly; see <http://greenbytes.de/tech/webdav/draft-ietf-httpbis-p4-conditional-05.html#rfc.section.5 

This is great.  I looked for this before starting my rant, but sorry  
to say I missed it.  Thanks!

Lisa