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

I've only seen a few responses to one aspect of this, so I'll restate  
as a set of proposals.

On 30/01/2008, at 2:55 PM, Mark Nottingham wrote:

> 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).

PROPOSAL: Remove 'requested variant' from terminology and define  
'selected representation' as (roughly): "The representation that would  
be returned by the server if the request method were GET, taking into  
consideration selecting headers, as specified by the Vary header's  
payload."

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

This should be a new issue; I'll add one.

> 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.

PROPOSAL: Define the response to PUT, POST, DELETE, and OPTIONS to  
carry a "status message," not a representation, UNLESS a Content- 
Location is present OR (in the case of POST) there is explicit  
freshness information. As such, ETags, etc. do not apply to them.

(This is a straw-man that I expect this to be controversial; just  
trying to get things going...)

> 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.

PROPOSAL:
A 201 response MAY contain an ETag response header field indicating  
the current value of the newly created resource's selected  
representation ETag (i.e., the ETag that would be returned if the same  
selecting headers had been sent in a GET request to it).

> 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.

PROPOSAL: s/requested variant/selected representation/

> 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'?

PROPOSAL: s/response for the same variant/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.

PROPOSAL: s/for the variant//; s/the particular variant/the particular  
representation/

> 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.

PROPOSAL: s/requested variant/selected representation/

> 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..

PROPOSAL: s/requested variant/selected representation/g; s/variant/ 
selected representation/g

And, add an issue about the implied divergence in the ETag and LM  
validation models.


>
>
>
>
> 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/
>
>


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

Received on Wednesday, 13 February 2008 06:26:44 UTC