Re: i69: Clarify "Requested Variant" [was: New "200 OK" status codes, PATCH & PROPFIND]

Roy, when you said you'd be happy to replace it with 'representation'  
do you mean
1) s/variant/representation/
or
2) s/requested variant/representation/
?

I think you mean #1, just want to make sure.

My 0.02;

It strikes me that if this term survives, or mutates into a new one,  
the definition should be tied directly to the concepts of selecting  
headers and the Vary header's payload. Tying it to conneg isn't good  
enough -- there are multiple types of conneg. If we buy that, the  
concept becomes more obviously tied to GET, and the issue of request  
bodies / other methods falls away. I also think that we should limit  
the use of such a term to places where we're talking about a response  
(see below).

(BTW, I note with interest that 14.44 doesn't classify Vary as a  
particular type of header, as all (AFAICT) other headers are.)

WRT a name -- how about 'selected representation'? This emphasises  
that it's the origin server doing the selection, not the client.

I also think (again, personally) that this general problem area would  
greatly benefit by having a crisper definition of and terminology  
around the status of POST, PUT, DELETE and other non-GET responses WRT  
whether they carry a representation or not.

I've pasted below all instances of 'variant' from 2616 outside of the  
term's definition, with some (again, personal) comments. I'm starting  
to suspect we have a number of inter-related issues here...


10.2.2 (201 Created):
> A 201 response MAY contain an ETag response header field indicating  
> the current value of the entity tag for the requested variant just  
> created, see section 14.19.
I find this just plain weird. On POST responses, it implies that you  
can negotiate for response headers on another resource and get them  
tunnelled back in the current response. If there's a Vary header  
present, does it apply to that resource too? If not, how do you know  
what the requested variant really was?

On PUT responses, it's a little more sane, but the language forces the  
requested variant to be the same as that just created; i.e., if  
there's a chance of conneg, the Accept-* headers have to be set in  
lockstep with what you're PUTting. So, you'd better not set Accept- 
Encoding: gzip unless the request entity is also content-coded with  
gzip, and AFAIK many implementations will have problems here, because  
these mechanisms tend to be taken out of developers' hands.


10.2.5 (204 No Content):
> The server has fulfilled the request but does not need to return an  
> entity-body, and might want to return updated metainformation. The  
> response MAY include new or updated metainformation in the form of  
> entity-headers, which if present SHOULD be associated with the  
> requested variant.

This makes internal sense; see comments about adjusting the definition  
above.


10.2.7 (206 Partial Content) and 10.3.5 (304 Not Modified):
> The response MUST include the following header fields:
[...]
> - Expires, Cache-Control, and/or Vary, if the field-value might  
> differ from that sent in any previous response for the same variant

Here's where IMO a distinct term does add some value; if we said  
'representation', it would be tied to a particular entity, which  
doesn't make much sense. OTOH 'variant' doesn't clarify things  
greatly, as it's currently defined. "...any previous instance of the  
selected representation'?


14.14 (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. A server SHOULD provide a Content-Location for the  
> variant corresponding to the response entity; especially in the case  
> where a resource has multiple entities associated with it, and those  
> entities actually have separate locations by which they might be  
> individually accessed, the server SHOULD provide a Content-Location  
> for the particular variant which is returned.

This is where things get fairly muddy. Variant is currently defined as  
a kind of representation, but here all of the sudden it's treated as a  
resource and given a URI. The first instance could probably be  
replaced by just 'resource', or just drop 'for the variant' entirely;  
in the second, 'representation' would probably suffice.


14.19 (ETag)
> The ETag response-header field provides the current value of the  
> entity tag for the requested variant.

Makes sense here, but 'requested/selected representation' would do  
just fine.


14.25 (If-Modified-Since)
> The If-Modified-Since request-header field is used with a method to  
> make it conditional: if the requested variant has not been modified  
> since the time specified in this field, an entity will not be  
> returned from the server [...]
> A GET method with an If-Modified-Since header and no Range header  
> requests that the identified entity be transferred only if it has  
> been modified since the date given by the If-Modified-Since header.  
> The algorithm for determining this includes the following cases: a)  
> If the request would normally result in anything other than a 200  
> (OK) status, or if the passed If-Modified-Since date is invalid, the  
> response is exactly the same as for a normal GET. A date which is  
> later than the server's current time is invalid. b) If the variant  
> has been modified since the If-Modified-Since date, the response is  
> exactly the same as for a normal GET. c) If the variant has not been  
> modified since a valid If- Modified-Since date, the server SHOULD  
> return a 304 (Not Modified) response.

14.28 (If-Unmodified-Since)
> If the requested variant has been modified since the specified time,  
> the server MUST NOT perform the requested operation, and MUST return  
> a 412 (Precondition Failed).

14.29 (Last-Modified)
> The Last-Modified entity-header field indicates the date and time at  
> which the origin server believes the variant was last modified.
Interestingly, Last-Modified validation is defined in terms of  
'requested variant', whereas ETag validation (If-Match, If-None-Match)  
seem to go out of their way to say that *any* entity that meets the  
conditional can be returned, and never mind the selecting headers. I'd  
be interested in hearing if any implementations actually do that, and  
unless some are found, I'd suggest we need to tighten up how ETag  
validation is defined..



On 10/01/2008, at 2:51 PM, Roy T. Fielding wrote:

> On Jan 8, 2008, at 10:39 PM, Mark Nottingham wrote:
>> Henrik mentioned a counterproposal in passing:
>>
>>> The "requested variant" is pretty clear. The variant returned had  
>>> the
>>> request been a GET request, or in case of the ETag returned by PUT  
>>> a GET
>>> request immediately after completion of the PUT.
>>
>> I've seen at least one other person agree (assumedly after  
>> appropriate wordsmithing). Roy, thoughts?
>
> Variants are not returned.  I am happy to replace variant with the
> right terminology (representation) if the WG doesn't mind.  That is
> part of what I was talking about earlier when I said that 2616
> often defines things in terms of server implementation when it
> really should restrict itself to the visible interface.
>
> ....Roy
>


--
Mark Nottingham     http://www.mnot.net/

Received on Wednesday, 30 January 2008 22:55:58 UTC