Ignore:
Timestamp:
03/09/12 05:54:40 (8 years ago)
Author:
fielding@…
Message:

(editorial) move content negotiation within section on representation

File:
1 edited

Legend:

Unmodified
Added
Removed
  • draft-ietf-httpbis/latest/p2-semantics.xml

    r1853 r1854  
    461461</t>
    462462</section>
     463
     464<section title="Content Negotiation" anchor="content.negotiation">
     465<t>
     466   HTTP responses include a representation which contains information for
     467   interpretation, whether by a human user or for further processing.
     468   Often, the server has different ways of representing the
     469   same information; for example, in different formats, languages,
     470   or using different character encodings.
     471</t>
     472<t>
     473   HTTP clients and their users might have different or variable
     474   capabilities, characteristics or preferences which would influence
     475   which representation, among those available from the server,
     476   would be best for the server to deliver. For this reason, HTTP
     477   provides mechanisms for "content negotiation" &mdash; a process of
     478   allowing selection of a representation of a given resource,
     479   when more than one is available.
     480</t>
     481<t>
     482   This specification defines two patterns of content negotiation;
     483   "server-driven", where the server selects the representation based
     484   upon the client's stated preferences, and "agent-driven" negotiation,
     485   where the server provides a list of representations for the client to
     486   choose from, based upon their metadata. In addition,  there are
     487   other patterns: some applications use an "active content" pattern,
     488   where the server returns active content which runs on the client
     489   and, based on client available parameters, selects additional
     490   resources to invoke. "Transparent Content Negotiation" (<xref target="RFC2295"/>)
     491   has also been proposed.
     492</t>
     493<t>
     494   These patterns are all widely used, and have trade-offs in applicability
     495   and practicality. In particular, when the number of preferences or
     496   capabilities to be expressed by a client are large (such as when many
     497   different formats are supported by a user-agent), server-driven
     498   negotiation becomes unwieldy, and might not be appropriate. Conversely,
     499   when the number of representations to choose from is very large,
     500   agent-driven negotiation might not be appropriate.
     501</t>
     502<t>
     503   Note that, in all cases, the supplier of representations has the
     504   responsibility for determining which representations might be
     505   considered to be the "same information".
     506</t>
     507
     508<section title="Server-driven Negotiation" anchor="server-driven.negotiation">
     509<t>
     510   If the selection of the best representation for a response is made by
     511   an algorithm located at the server, it is called server-driven
     512   negotiation. Selection is based on the available representations of
     513   the response (the dimensions over which it can vary; e.g., language,
     514   content-coding, etc.) and the contents of particular header fields in
     515   the request message or on other information pertaining to the request
     516   (such as the network address of the client).
     517</t>
     518<t>
     519   Server-driven negotiation is advantageous when the algorithm for
     520   selecting from among the available representations is difficult to
     521   describe to the user agent, or when the server desires to send its
     522   "best guess" to the client along with the first response (hoping to
     523   avoid the round-trip delay of a subsequent request if the "best
     524   guess" is good enough for the user). In order to improve the server's
     525   guess, the user agent &MAY; include request header fields (<x:ref>Accept</x:ref>,
     526   <x:ref>Accept-Language</x:ref>, <x:ref>Accept-Encoding</x:ref>, etc.) which describe its
     527   preferences for such a response.
     528</t>
     529<t>
     530   Server-driven negotiation has disadvantages:
     531  <list style="numbers">
     532    <t>
     533         It is impossible for the server to accurately determine what
     534         might be "best" for any given user, since that would require
     535         complete knowledge of both the capabilities of the user agent
     536         and the intended use for the response (e.g., does the user want
     537         to view it on screen or print it on paper?).
     538    </t>
     539    <t>
     540         Having the user agent describe its capabilities in every
     541         request can be both very inefficient (given that only a small
     542         percentage of responses have multiple representations) and a
     543         potential violation of the user's privacy.
     544    </t>
     545    <t>
     546         It complicates the implementation of an origin server and the
     547         algorithms for generating responses to a request.
     548    </t>
     549    <t>
     550         It might limit a public cache's ability to use the same response
     551         for multiple user's requests.
     552    </t>
     553  </list>
     554</t>
     555<t>
     556   Server-driven negotiation allows the user agent to specify its preferences,
     557   but it cannot expect responses to always honor them. For example, the origin
     558   server might not implement server-driven negotiation, or it might decide that
     559   sending a response that doesn't conform to them is better than sending a <x:ref>406
     560   (Not Acceptable)</x:ref> response.
     561</t>
     562<t>
     563   HTTP/1.1 includes the following header fields for enabling
     564   server-driven negotiation through description of user agent
     565   capabilities and user preferences: <x:ref>Accept</x:ref>
     566   (<xref target="header.accept"/>), <x:ref>Accept-Charset</x:ref>
     567   (<xref target="header.accept-charset"/>), <x:ref>Accept-Encoding</x:ref>
     568   (<xref target="header.accept-encoding"/>), <x:ref>Accept-Language</x:ref>
     569   (<xref target="header.accept-language"/>), and <x:ref>User-Agent</x:ref>
     570   (&header-user-agent;).
     571   However, an origin server is not limited to these dimensions and &MAY; vary
     572   the response based on any aspect of the request, including aspects
     573   of the connection (e.g., IP address) or information within extension
     574   header fields not defined by this specification.
     575</t>
     576<x:note>
     577  <t>
     578    &Note; In practice, <x:ref>User-Agent</x:ref> based negotiation is fragile,
     579    because new clients might not be recognized.
     580  </t>
     581</x:note>
     582<t>
     583   The <x:ref>Vary</x:ref> header field (&header-vary;) can be used to express
     584   the parameters the server uses to select a representation that is subject to
     585   server-driven negotiation.
     586</t>
     587</section>
     588
     589<section title="Agent-driven Negotiation" anchor="agent-driven.negotiation">
     590<t>
     591   With agent-driven negotiation, selection of the best representation
     592   for a response is performed by the user agent after receiving an
     593   initial response from the origin server. Selection is based on a list
     594   of the available representations of the response included within the
     595   header fields or body of the initial response, with each
     596   representation identified by its own URI. Selection from among the
     597   representations can be performed automatically (if the user agent is
     598   capable of doing so) or manually by the user selecting from a
     599   generated (possibly hypertext) menu.
     600</t>
     601<t>
     602   Agent-driven negotiation is advantageous when the response would vary
     603   over commonly-used dimensions (such as type, language, or encoding),
     604   when the origin server is unable to determine a user agent's
     605   capabilities from examining the request, and generally when public
     606   caches are used to distribute server load and reduce network usage.
     607</t>
     608<t>
     609   Agent-driven negotiation suffers from the disadvantage of needing a
     610   second request to obtain the best alternate representation. This
     611   second request is only efficient when caching is used. In addition,
     612   this specification does not define any mechanism for supporting
     613   automatic selection, though it also does not prevent any such
     614   mechanism from being developed as an extension and used within
     615   HTTP/1.1.
     616</t>
     617<t>
     618   This specification defines the <x:ref>300 (Multiple Choices)</x:ref> and
     619   <x:ref>406 (Not Acceptable)</x:ref> status codes for enabling agent-driven
     620   negotiation when the server is unwilling or unable to provide a varying
     621   response using server-driven negotiation.
     622</t>
     623</section>
     624
     625<section title="Quality Values" anchor="quality.values">
     626  <x:anchor-alias value="weight"/>
     627  <x:anchor-alias value="qvalue"/>
     628<t>
     629   Many of the request header fields for server-driven content negotiation
     630   use a common parameter, named "q", to assign a relative "weight" to the
     631   preference for that associated kind of content.
     632   This weight is referred to as a "quality value" (or "qvalue") because
     633   the same parameter name is often used within server configurations to
     634   assign a weight to the relative quality of the various representations
     635   that can be selected for a resource.
     636</t>
     637<t>
     638   The weight is normalized to a real number in the range 0 through 1,
     639   where 0.001 is the least preferred and 1 is the most preferred;
     640   a value of 0 means "not acceptable". If no "q" parameter is present,
     641   the default weight is 1.
     642</t>
     643<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="weight"/><iref primary="true" item="Grammar" subitem="qvalue"/>
     644  <x:ref>weight</x:ref> = <x:ref>OWS</x:ref> ";" <x:ref>OWS</x:ref> "q=" <x:ref>qvalue</x:ref>
     645  <x:ref>qvalue</x:ref> = ( "0" [ "." 0*3<x:ref>DIGIT</x:ref> ] )
     646         / ( "1" [ "." 0*3("0") ] )
     647</artwork></figure>
     648<t>
     649   A sender of qvalue &MUST-NOT; generate more than three digits after the
     650   decimal point. User configuration of these values ought to be limited in
     651   the same fashion.
     652</t>
     653</section>
     654</section>
    463655</section>
    464656
     
    26882880   from the message body by decoding any <x:ref>Transfer-Encoding</x:ref> that
    26892881   might have been applied to ensure safe and proper transfer of the message.
    2690 </t>
    2691 </section>
    2692 </section>
    2693 
    2694 <section title="Content Negotiation" anchor="content.negotiation">
    2695 <t>
    2696    HTTP responses include a representation which contains information for
    2697    interpretation, whether by a human user or for further processing.
    2698    Often, the server has different ways of representing the
    2699    same information; for example, in different formats, languages,
    2700    or using different character encodings.
    2701 </t>
    2702 <t>
    2703    HTTP clients and their users might have different or variable
    2704    capabilities, characteristics or preferences which would influence
    2705    which representation, among those available from the server,
    2706    would be best for the server to deliver. For this reason, HTTP
    2707    provides mechanisms for "content negotiation" &mdash; a process of
    2708    allowing selection of a representation of a given resource,
    2709    when more than one is available.
    2710 </t>
    2711 <t>
    2712    This specification defines two patterns of content negotiation;
    2713    "server-driven", where the server selects the representation based
    2714    upon the client's stated preferences, and "agent-driven" negotiation,
    2715    where the server provides a list of representations for the client to
    2716    choose from, based upon their metadata. In addition,  there are
    2717    other patterns: some applications use an "active content" pattern,
    2718    where the server returns active content which runs on the client
    2719    and, based on client available parameters, selects additional
    2720    resources to invoke. "Transparent Content Negotiation" (<xref target="RFC2295"/>)
    2721    has also been proposed.
    2722 </t>
    2723 <t>
    2724    These patterns are all widely used, and have trade-offs in applicability
    2725    and practicality. In particular, when the number of preferences or
    2726    capabilities to be expressed by a client are large (such as when many
    2727    different formats are supported by a user-agent), server-driven
    2728    negotiation becomes unwieldy, and might not be appropriate. Conversely,
    2729    when the number of representations to choose from is very large,
    2730    agent-driven negotiation might not be appropriate.
    2731 </t>
    2732 <t>
    2733    Note that, in all cases, the supplier of representations has the
    2734    responsibility for determining which representations might be
    2735    considered to be the "same information".
    2736 </t>
    2737 
    2738 <section title="Server-driven Negotiation" anchor="server-driven.negotiation">
    2739 <t>
    2740    If the selection of the best representation for a response is made by
    2741    an algorithm located at the server, it is called server-driven
    2742    negotiation. Selection is based on the available representations of
    2743    the response (the dimensions over which it can vary; e.g., language,
    2744    content-coding, etc.) and the contents of particular header fields in
    2745    the request message or on other information pertaining to the request
    2746    (such as the network address of the client).
    2747 </t>
    2748 <t>
    2749    Server-driven negotiation is advantageous when the algorithm for
    2750    selecting from among the available representations is difficult to
    2751    describe to the user agent, or when the server desires to send its
    2752    "best guess" to the client along with the first response (hoping to
    2753    avoid the round-trip delay of a subsequent request if the "best
    2754    guess" is good enough for the user). In order to improve the server's
    2755    guess, the user agent &MAY; include request header fields (<x:ref>Accept</x:ref>,
    2756    <x:ref>Accept-Language</x:ref>, <x:ref>Accept-Encoding</x:ref>, etc.) which describe its
    2757    preferences for such a response.
    2758 </t>
    2759 <t>
    2760    Server-driven negotiation has disadvantages:
    2761   <list style="numbers">
    2762     <t>
    2763          It is impossible for the server to accurately determine what
    2764          might be "best" for any given user, since that would require
    2765          complete knowledge of both the capabilities of the user agent
    2766          and the intended use for the response (e.g., does the user want
    2767          to view it on screen or print it on paper?).
    2768     </t>
    2769     <t>
    2770          Having the user agent describe its capabilities in every
    2771          request can be both very inefficient (given that only a small
    2772          percentage of responses have multiple representations) and a
    2773          potential violation of the user's privacy.
    2774     </t>
    2775     <t>
    2776          It complicates the implementation of an origin server and the
    2777          algorithms for generating responses to a request.
    2778     </t>
    2779     <t>
    2780          It might limit a public cache's ability to use the same response
    2781          for multiple user's requests.
    2782     </t>
    2783   </list>
    2784 </t>
    2785 <t>
    2786    Server-driven negotiation allows the user agent to specify its preferences,
    2787    but it cannot expect responses to always honor them. For example, the origin
    2788    server might not implement server-driven negotiation, or it might decide that
    2789    sending a response that doesn't conform to them is better than sending a <x:ref>406
    2790    (Not Acceptable)</x:ref> response.
    2791 </t>
    2792 <t>
    2793    HTTP/1.1 includes the following header fields for enabling
    2794    server-driven negotiation through description of user agent
    2795    capabilities and user preferences: <x:ref>Accept</x:ref>
    2796    (<xref target="header.accept"/>), <x:ref>Accept-Charset</x:ref>
    2797    (<xref target="header.accept-charset"/>), <x:ref>Accept-Encoding</x:ref>
    2798    (<xref target="header.accept-encoding"/>), <x:ref>Accept-Language</x:ref>
    2799    (<xref target="header.accept-language"/>), and <x:ref>User-Agent</x:ref>
    2800    (&header-user-agent;).
    2801    However, an origin server is not limited to these dimensions and &MAY; vary
    2802    the response based on any aspect of the request, including aspects
    2803    of the connection (e.g., IP address) or information within extension
    2804    header fields not defined by this specification.
    2805 </t>
    2806 <x:note>
    2807   <t>
    2808     &Note; In practice, <x:ref>User-Agent</x:ref> based negotiation is fragile,
    2809     because new clients might not be recognized.
    2810   </t>
    2811 </x:note>
    2812 <t>
    2813    The <x:ref>Vary</x:ref> header field (&header-vary;) can be used to express
    2814    the parameters the server uses to select a representation that is subject to
    2815    server-driven negotiation.
    2816 </t>
    2817 </section>
    2818 
    2819 <section title="Agent-driven Negotiation" anchor="agent-driven.negotiation">
    2820 <t>
    2821    With agent-driven negotiation, selection of the best representation
    2822    for a response is performed by the user agent after receiving an
    2823    initial response from the origin server. Selection is based on a list
    2824    of the available representations of the response included within the
    2825    header fields or body of the initial response, with each
    2826    representation identified by its own URI. Selection from among the
    2827    representations can be performed automatically (if the user agent is
    2828    capable of doing so) or manually by the user selecting from a
    2829    generated (possibly hypertext) menu.
    2830 </t>
    2831 <t>
    2832    Agent-driven negotiation is advantageous when the response would vary
    2833    over commonly-used dimensions (such as type, language, or encoding),
    2834    when the origin server is unable to determine a user agent's
    2835    capabilities from examining the request, and generally when public
    2836    caches are used to distribute server load and reduce network usage.
    2837 </t>
    2838 <t>
    2839    Agent-driven negotiation suffers from the disadvantage of needing a
    2840    second request to obtain the best alternate representation. This
    2841    second request is only efficient when caching is used. In addition,
    2842    this specification does not define any mechanism for supporting
    2843    automatic selection, though it also does not prevent any such
    2844    mechanism from being developed as an extension and used within
    2845    HTTP/1.1.
    2846 </t>
    2847 <t>
    2848    This specification defines the <x:ref>300 (Multiple Choices)</x:ref> and
    2849    <x:ref>406 (Not Acceptable)</x:ref> status codes for enabling agent-driven
    2850    negotiation when the server is unwilling or unable to provide a varying
    2851    response using server-driven negotiation.
    2852 </t>
    2853 </section>
    2854 
    2855 <section title="Quality Values" anchor="quality.values">
    2856   <x:anchor-alias value="weight"/>
    2857   <x:anchor-alias value="qvalue"/>
    2858 <t>
    2859    Many of the request header fields for server-driven content negotiation
    2860    use a common parameter, named "q", to assign a relative "weight" to the
    2861    preference for that associated kind of content.
    2862    This weight is referred to as a "quality value" (or "qvalue") because
    2863    the same parameter name is often used within server configurations to
    2864    assign a weight to the relative quality of the various representations
    2865    that can be selected for a resource.
    2866 </t>
    2867 <t>
    2868    The weight is normalized to a real number in the range 0 through 1,
    2869    where 0.001 is the least preferred and 1 is the most preferred;
    2870    a value of 0 means "not acceptable". If no "q" parameter is present,
    2871    the default weight is 1.
    2872 </t>
    2873 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="weight"/><iref primary="true" item="Grammar" subitem="qvalue"/>
    2874   <x:ref>weight</x:ref> = <x:ref>OWS</x:ref> ";" <x:ref>OWS</x:ref> "q=" <x:ref>qvalue</x:ref>
    2875   <x:ref>qvalue</x:ref> = ( "0" [ "." 0*3<x:ref>DIGIT</x:ref> ] )
    2876          / ( "1" [ "." 0*3("0") ] )
    2877 </artwork></figure>
    2878 <t>
    2879    A sender of qvalue &MUST-NOT; generate more than three digits after the
    2880    decimal point. User configuration of these values ought to be limited in
    2881    the same fashion.
    28822882</t>
    28832883</section>
Note: See TracChangeset for help on using the changeset viewer.