Re: Prefer Draft Feedback

On 2011-12-13 20:42, James Snell wrote:
> ...
>> Not convinced. Where's the difference? If the response without "Prefer"
>> would have been cacheable, and the presence of the Prefer header field
>> changes the response I receive, how is that *not* content negotiation?
>>
>> [snip]
>
> Ok, here's another run at explaining this... let me know if it makes
> sense and is convincing enough ;-)
> ...

You may or may not have noticed that we had a perfect storm of 
back-and-forth on public-html-comments@w3.org today. It was about 
whether selecting the type of a response (status vs representation vs 
...) is some kind of content negotiation, that should or should not be 
triggered using Accept:.

In that discussion it became clear to me that what we really want to 
select are different resources that are related to the outcome of the 
operation, such as:

- status
- new representation
- monitor resource
- something else (next step in a UI workflow?)

Maybe that would make at least the return-* preferences clearer.

> As I've pointed out, the Prefer mechanism is essentially
> behavior-negotiation, which means, it allows the client a means of
> politely asking the server to act a particular way when processing a
> request. In the case of the return-representation, return-minimal and
> return-accepted preferences, it is essentially negotiating with the
> server about the processing model for a request. Whether the content

I agree for -accept, but -minimal vs -representation doesn't seem to 
affect processing but just the type^h^h^h^hkind of response (*not* the 
media type).

> actually returned by the server is cacheable or not is a different
> question that will be dependent on a number of factors including the
> specific response code, request method and effective cache-controls.
> Asking a server to return a representation a modified resource has no
> impact on whether that representation is cacheable. Asking the server
> to return a minimal response (e.g. 204 No Content) also has no impact
> on whether the representation is cacheable. Let's look at an
> example...

Yes.

> Suppose we have an api that supports to use of the
> return-representation and return-minimal preferences... basically,
> when I modify content, I can send Prefer: return-representation or
> Prefer: return-minimal. Specifying either of these on a GET makes
> absolutely no sense given that return-representation implied in the
> nature of GET and return-minimal should still return the

Absolutely. It might be good to state this in the spec.

> representation. If an application supports alternate representations
> (minimal and verbose) of a resource, then it has to be prepared to
> deal with cacheability independently of whether Prefer is used or not.
> So assume we POST a resource to a collection and want a minimal
> reponse...
>
>    POST /collection HTTP/1.1
>    Host: example.org
>    Content-Type: text/plain
>    Prefer: return-minimal
>
>    {Data}
>
> ...
>
>    HTTP/1.1 201 Created
>    Location: http://example.org/collection/1
>    Content-Length: 0
>
>
> Ok, since this is a POST (content modification), the default
> assumption is that the response is not cacheable (per
> http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-17#section-6.5).
> The response would have to contain specific caching information in
> order to be cacheable. So here, it's not a problem.
>
> Let's look at return-representation now...
>
>
>    POST /collection HTTP/1.1
>    Host: example.org
>    Content-Type: text/plain
>    Prefer: return-representation
>
>    {Data}
>
> ...
>
>    HTTP/1.1 201 Created
>    Location: http://example.org/collection/1
>    Content-Type: text/plain
>    Content-Length: 6
>
>    {Data}

Content-Location missing here?

> Ok, in this example, again, the default assumption is that the
> response is not cacheable. It doesn't matter that
> return-representation was used. The server would have to include
> additional freshness information in the response in order to make the
> request cacheable (e.g a cache-control header).

Yes.

> PUT and PATCH would be handled the same... whether the response is
> cacheable or not has absolutely nothing to do with which preference
> was passed in.
>
> The same considerations apply to returning a 202 Accepted for
> asynchronous processing using the return-accepted preference... again,
> because of the requests used, and the nature of handling 202
> responses, the cacheability of the response is completely independent
> of the specific preference applied.
>
> So for the various return-* (and wait) preferences currently defined
> in the spec, it's clear that they are not content-negotiation
> mechanisms.
>
> Contrast that with the detail preference that I removed. In that case,
> the preference specifically deals with the amount of information to
> include in the response. Let's assume I left that in... per the
> definition of the preference, it's up to the server to figure out how
> it applies. The original intent for the preference is to affect the
> amount of detail included in error responses in an api (4xx and 5xx
> responses), primarily for debugging purposes. Again, for modification
> requests (DELETE, PUT, POST, PATCH, etc) the default cacheability of
> the response has absolutely nothing to do with the preference
> specified, and anyone who is caching error responses that could
> potentially contain request-specific content is asking for trouble
> anyway. (btw, it's interesting the the http spec is completely silent
> on the cacheability of 4xx and 5xx responses with the exception of
> 410). If a specific API wishes to apply the Detail preference to
> non-error output, then it has to be prepared to deal with the caching
> consequences regardless or whether Prefer is used or not. That said,
> however, an API that allows non-error variability in the verboseness
> of the non-error output would be better off defining a querystring
> parameter specifying the verboseness than using Prefer. Prefer: detail
> works great for debugging error responses, not so much for regular api
> use. Regardless, use of Prefer: detail would not inherently impact the
> caching of the response.

When used with GET, with Vary. Yes.

> Convinced yet?

Maybe. I think the key is to clarify that for return-*, Prefer doesn't 
select different representation types for the same resource, but 
actually defines what resource to represent in the response.

> Now, if I defined a preference like "Prefer: return-atom", that would
> be Just Plain Silly. Preferences should be limited to behavioral
> options (how to handle a request, how to handle the response, how to
> deal with various error conditions, etc) leaving the content options
> up to the request uri and various Accept-* headers, etc.

Yes.

Best regards, Julian

Received on Tuesday, 13 December 2011 20:05:04 UTC