Re: Prefer Draft Feedback

Ok... so let's walk through the scenarios a bit to see if we can't put
this content-location question to bed for good...

Once again, the requirement is simple: When a client posts a request
to a server, the server can return either a representation of the
resource or a representation of the request status, there is currently
no reliable means of determining which is being returned beyond the
following statements in httpbis part2, from section 5.1:

    ...
    3. If the response has a Content-Location header field, and that URI
    is the same as the effective request URI, the response payload is
    a representation of the target resource.

    4. If the response has a Content-Location header field, and that URI
    is not the same as the effective request URI, then the response
    asserts that its payload is a representation of the resource
    identified by the Content-Location URI.  However, such an
    assertion cannot be trusted unless it can be verified by other
    means (not defined by HTTP).
    ...

For most operations, the distinction between the status and
representation is going to be pretty simple.. for PUT, for instance,
matching the Content-Location to the effective Request URI can be
generally sufficient. There are edge cases where the type of response
becomes ambiguous.

The one case where this falls down.. and so far, the only case I've
seen where the Content-Location/Request URI rule doesn't work, is the
case such as in the Atom Publishing Protocol where an entity is POSTed
to one URL resulting in the creation of a new resource with a
different URL. The fact that the response contains a Content-Location
header that differs from the Effective Request URI is not sufficient
to tell us whether the returned entity is a representation of the
created resource.

For the Atom case, there is a workable solution given that a
successful POST to a Collection URI also returns a Location header
thanks to the defined semantics of the 201 Created response (httpbis
part 2, section 7.2.2)... for instance:

POST /collection HTTP/1.1
Host: example.org
  ...

HTTP/1.1 201 Created
Location: /collection/item1
Content-Location: /collection/item1

In this case, we can apply the additional heuristic that if the
response has both a Content-Location AND Location header that match,
the returned entity is a representation of the created resource,
however, if the Content-Location and Location headers do not match,
the returned entity *might* be a representation of the request status.
Notice the *might*... there are edge cases where if the two fields
differ, it may not actually be a status response. The question is
whether that ambiguity is acceptable. I know that in the use cases
where I've implemented this, use of Preference-Applied hasn't been
strictly required.

Another example tho, to tease it out further...

PATCH /some/resource HTTP/1.1
Prefer: return-status
Content-Type: application/mypatchformat

...

HTTP/1.1 200 OK
Content-Type: application/json
Content-Location: /status-messages/1

{"changed-elements":["foo","bar","baz"]}

As opposed to...

PATCH /some/resource HTTP/1.1
Prefer: return-representation
Content-Type: application/mypatchformat

...

HTTP/1.1 200 OK
Content-Type: application/json
Content-Location: /some/resource

{"foo":"1","bar":"2","baz":"3"}

Ok, so with this, in case 2, the fact that the effective request URI
matches the Content-Location means we have a representation of the
resource. In case 1, it could be a status message but we cannot be
100% sure...

Hmm... ok, so drawing this out highlights a couple of very important
point that I may have missed before: a) The use cases for requesting
the resource representation are more prevalent that the use cases for
requesting the status response and b) even when requesting a status
response, we cannot be 100% that's what we're getting, forcing us to
inspect the data anyway. Given that, I'm wondering if we can simply
drop the return-status preference all together, making the option
"return-representation" or "do the default" that requires us to
examine the response.

GET with Prefer: return-representation is nonsensical since GET always
returns the representation
POST with Prefer: return-representation is only relevant if the POST
is being used to create a resource, in which case the 201 Response
with both Location and Content-Location headers can be returned...
PUT with Prefer: return-representation is handled easily by matching
the Content-Location to the effective request URI
DELETE with Prefer: return-representation is nonsensical
PATCH with Prefer: return-representation is essentially same as PUT

return-status isn't strictly necessary in any of these cases. Dropping
it from the spec eliminates the need to differentiate which preference
was applied as we'd just assume that all responses that aren't
unambiguously representations of the resource are likely status
responses.

Sorry for rambling a bit on that, but does that make sense or am I
missing something?

- James

On Wed, Dec 7, 2011 at 7:53 AM, Alex Rousskov
<rousskov@measurement-factory.com> wrote:
> On 12/06/2011 11:36 PM, Mark Nottingham wrote:
>>
>> On 07/12/2011, at 11:57 AM, James Snell wrote:
>>
>>> Current iterations based on today's feedback...
>>>
>>> http://www.ietf.org/id/draft-snell-http-prefer-06.txt
>>>
>>> Change summary:
>>>
>>> - replaced user-agent with client
>>
>> What's the reasoning here? Do you expect intermediaries to have preferences?
>
>
> IMO, the general reasoning should be "we do not want to exclude
> intermediaries without a specific reason because some of them might find
> the new mechanism useful". This is especially true when the mechanism
> can be extended.
>
> In this specific case, we have already come up with at least one
> possible use: wait=10 preference set by a proxy in a poorly connected
> environment when validating a cached response. See this thread for more
> info.
>
>
>>> - brought Preference-Applied back
>
>> This needs to be discussed. I'm very uneasy about turning this into
>> Yet Another HTTP Negotiation Mechanism.
>
> If there is an existing mechanism that can be reused to acknowledge
> which preference was honored, we should reuse it. Otherwise, a "yet
> another" acknowledgement mechanism seems justified.
>
> I am not an expert on this, but my understanding of the arguments
> presented so far is that reusing Content-Location to indicate whether
> the status preference was applied is not going to cover all possible use
> cases.
>
> I also find the Preference-Applied acknowledgement mechanism useful for
> debugging/troubleshooting.
>
>
> [ N.B. If "Preference-Applied" stays, please consider renaming it to
> "Preferred" to save a few bytes and to remove the implication that all
> preferences can be "applied" rather than honored, etc. ]
>
>
> Thank you,
>
> Alex.

Received on Wednesday, 7 December 2011 18:07:17 UTC