Re: Prefer Draft Feedback

On 2011-12-03 12:16, Julian Reschke wrote:
> On 2011-12-03 00:01, James Snell wrote:
>> All,
>>
>> I would like to take a quick moment to solicit feedback on the current
>> version of the HTTP Prefer Header specification:
>>
>> http://tools.ietf.org/html/draft-snell-http-prefer-04
>>
>> The draft should be pretty well self-explanatory. There are some
>> highly tentative pieces included in this draft that may likely be
>> removed in a future iteration. They have been included now primarily
>> for the purpose of soliciting feedback on their overall utility.
>> ...
>
> Will review.
>
> One thing I already noticed is that the spec does the same mistake most
> other header field definitions make; it defines an extensible syntax but
> then special cases the header field it defines itself.
>
> Parsing should be uniform.
>
> So,
>
> - if you take value-less tokens, you need to state whether
>
> x
>
> x=
>
> x=""
>
> are equivalent or not.
>
> - if values can be tokens or quoted-strings, you should state that both
> notations are equivalent, and are allowed everywhere, so are
>
> priority=100
>
> and
>
> priority="100"
>
> the same thing?
>
> Best regards, Julian

OK, here's more feedback:

2.  The Prefer Request Header

    The Prefer request-header is used to indicate that particular server
    behaviors are preferred by the user-agent, but not required for
    successful completion of the request.  Prefer is similar in nature to
    the Expect header defined by [RFC2616] with the exception that
    servers are allowed to ignore stated preferences.

      Prefer       =  "Prefer" ":" 1#preference

      preference   =  (return-accepted /
                      return-no-content /
                      return-content /
                      return-status /
                      wait /
                      priority /
                      handling /
                      detail /
                      preference-extension)
                      *prefer-params
      preference-value = token / quoted-string
      preference-token = token [ "=" preference-value ]
      preference-extension =  preference-token
      prefer-params =  ";" preference-token

1) Do not define the individual tokens in the grammar; consumers should 
not special-case them. Just define the generic grammar, then define the 
invididual tokens in prose.

2) You need to say what ABNF form you use. Right now it looks like 
HTTPbis ABNF, in which case you need to reference HTTPbis Part 1.

3) Need to think about whitespace between tokens and delimiters!

4) So preference token can have optional values, plus optional 
parameters. This looks like one degree of freedom too much. The value of 
a token could always be replaced by a parameter on the value. In any 
case, as the grammar as currently proposed is relatively complex, a set 
of examples would be very good.

5) Need to state recurrence rules (multiple same-named tokens, repeating 
parameters).

6) Need to state case-matching for token and parameter names.




    Comparison of preference tokens is case-insensitive for unquoted
    tokens and is case-sensitive for quoted-string preference-extensions
    and prefer-params values.

Not good, this differs from all header fields. Make the token *names* 
case-insensitive and the values case-sensitive (no matter whether token 
or quoted string)

    Note that the application of a preference by the server MAY affect
    the caching characteristics of the response.  Specifically, should
    the application of a preference result in a variance to the
    representation returned by a cacheable response, a Vary header SHOULD

MUST?

    be included listing the Prefer header as one of the selecting header
    fields.

4.  The "return-content" Preference

    The "return-content" preference indicates that the user-agent prefers
    that the server include an entity representing the current state of
    the resource in the response to a successful request.

      return-content = "return-content"

Maybe this should be called "return-representation".


5.  The "return-status" Preference

    The "return-status" preference indicates that the user-agent prefers
    the server to include an entity describing the status of the request
    in the response as opposed to returning a representation of the
    current state of the resource.

      return-status = "return-status"

    When honoring the "return-status" preference, the server SHOULD NOT
    include a Content-Location header in the response.

Why not?


6.  The "return-no-content" Preference

    The "return-no-content" preference indicates that the user-agent
    wishes the server to not include an entity in the response to a
    successful request.  Typically, such responses would use the 204 No
    Content status, but other codes MAY be used as appropriate.
    Regardless of the status returned, when honoring the "return-no-
    content" preference, the server MUST NOT include an entity within the
    response.

      return-no-content = "return-no-content"

    The "return-no-content" preference is intended to provide a means of
    optimizing communication between the user-agent and server by
    reducing the amount of data the server is required to return to the
    user-agent following a modification request.  This can be
    particularly useful, for instance, when communicating with limited-
    bandwidth mobile devices or when the user-agent simply does not
    require any further information about the result of a request beyond
    knowing if it was successfully processed.

"return-minimal"?


7.  The "wait" Preference

    The "wait" preference can be used to establish an upper bound on the
    length of time, in seconds, the user-agent is willing to wait for a
    response, after which the user-agent may choose to abandon the
    request.  In the case generating a response will take longer than the
    time specified, the server, or proxy, can choose to either return a
    202 Accepted response, cancel processing, or continue attempting to
    complete the request.

      wait = "wait" "=" delta-seconds

Potential overlap with other work?


8.  The "priority" Preference

-1; maybe later.


9.  The "strict" and "lenient" Processing Preferences

+0

10.  The "detail" Preference

+0

11.  Registered Preferences

    Well-defined preferences can be registered for convenience and/or to
    promote reuse by other applications.  This specification establishes
    an IANA registry of such relation types see Section Section 12.1.

    Registered preference names MUST conform to the token rule, and MUST
    be compared character-by-character in a case-insensitive fashion.

No, this is inconsistent with the use in similar header fields (like 
Cache-Control)


13.  Security Considerations

    Specific preferences requested by a client can introduce security
    considerations and concerns beyond those discussed in [RFC2616].

Be consistent in referencing HTTPbis *or* RFC2616.

Editorial:

Throughout: s/header/header field/

Received on Sunday, 4 December 2011 19:07:36 UTC