granicus.if.org Git - apache/blob - docs/manual/content-negotiation.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
   4 <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
   5 <!--
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7               This file is generated from xml source: DO NOT EDIT
   8         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   9       -->
  10 <title>Content Negotiation - Apache HTTP Server Version 2.5</title>
  11 <link href="./style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  12 <link href="./style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  13 <link href="./style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="./style/css/prettify.css" />
  14 <script src="./style/scripts/prettify.min.js" type="text/javascript">
  15 </script>
  16
  17 <link href="./images/favicon.ico" rel="shortcut icon" /></head>
  18 <body id="manual-page"><div id="page-header">
  19 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p>
  20 <p class="apache">Apache HTTP Server Version 2.5</p>
  21 <img alt="" src="./images/feather.png" /></div>
  22 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="./images/left.gif" /></a></div>
  23 <div id="path">
  24 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="./">Version 2.5</a></div><div id="page-content"><div id="preamble"><h1>Content Negotiation</h1>
  25 <div class="toplang">
  26 <p><span>Available Languages: </span><a href="./en/content-negotiation.html" title="English">&nbsp;en&nbsp;</a> |
  27 <a href="./fr/content-negotiation.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a> |
  28 <a href="./ja/content-negotiation.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
  29 <a href="./ko/content-negotiation.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a> |
  30 <a href="./tr/content-negotiation.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</a></p>
  31 </div>
  32
  33
  34     <p>Apache HTTPD supports content negotiation as described in
  35     the HTTP/1.1 specification. It can choose the best
  36     representation of a resource based on the browser-supplied
  37     preferences for media type, languages, character set and
  38     encoding. It also implements a couple of features to give
  39     more intelligent handling of requests from browsers that send
  40     incomplete negotiation information.</p>
  41
  42     <p>Content negotiation is provided by the
  43     <code class="module"><a href="./mod/mod_negotiation.html">mod_negotiation</a></code> module, which is compiled in
  44     by default.</p>
  45 </div>
  46 <div id="quickview"><ul id="toc"><li><img alt="" src="./images/down.gif" /> <a href="#about">About Content Negotiation</a></li>
  47 <li><img alt="" src="./images/down.gif" /> <a href="#negotiation">Negotiation in httpd</a></li>
  48 <li><img alt="" src="./images/down.gif" /> <a href="#methods">The Negotiation Methods</a></li>
  49 <li><img alt="" src="./images/down.gif" /> <a href="#better">Fiddling with Quality
  50     Values</a></li>
  51 <li><img alt="" src="./images/down.gif" /> <a href="#extensions">Extensions to Transparent Content
  52 Negotiation</a></li>
  53 <li><img alt="" src="./images/down.gif" /> <a href="#naming">Note on hyperlinks and naming conventions</a></li>
  54 <li><img alt="" src="./images/down.gif" /> <a href="#caching">Note on Caching</a></li>
  55 </ul><h3>See also</h3><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
  56 <div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  57 <div class="section">
  58 <h2><a name="about" id="about">About Content Negotiation</a> <a title="Permanent link" href="#about" class="permalink">&para;</a></h2>
  59
  60     <p>A resource may be available in several different
  61     representations. For example, it might be available in
  62     different languages or different media types, or a combination.
  63     One way of selecting the most appropriate choice is to give the
  64     user an index page, and let them select. However it is often
  65     possible for the server to choose automatically. This works
  66     because browsers can send, as part of each request, information
  67     about what representations they prefer. For example, a browser
  68     could indicate that it would like to see information in French,
  69     if possible, else English will do. Browsers indicate their
  70     preferences by headers in the request. To request only French
  71     representations, the browser would send</p>
  72
  73 <div class="example"><p><code>Accept-Language: fr</code></p></div>
  74
  75     <p>Note that this preference will only be applied when there is
  76     a choice of representations and they vary by language.</p>
  77
  78     <p>As an example of a more complex request, this browser has
  79     been configured to accept French and English, but prefer
  80     French, and to accept various media types, preferring HTML over
  81     plain text or other text types, and preferring GIF or JPEG over
  82     other media types, but also allowing any other media type as a
  83     last resort:</p>
  84
  85 <div class="example"><p><code>
  86   Accept-Language: fr; q=1.0, en; q=0.5<br />
  87   Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6, image/jpeg; q=0.6, image/*; q=0.5, */*; q=0.1
  88 </code></p></div>
  89
  90     <p>httpd supports 'server driven' content negotiation, as
  91     defined in the HTTP/1.1 specification. It fully supports the
  92     <code>Accept</code>, <code>Accept-Language</code>,
  93     <code>Accept-Charset</code> and <code>Accept-Encoding</code>
  94     request headers. httpd also supports 'transparent'
  95     content negotiation, which is an experimental negotiation
  96     protocol defined in RFC 2295 and RFC 2296. It does not offer
  97     support for 'feature negotiation' as defined in these RFCs.</p>
  98
  99     <p>A <strong>resource</strong> is a conceptual entity
 100     identified by a URI (RFC 2396). An HTTP server like Apache HTTP Server
 101     provides access to <strong>representations</strong> of the
 102     resource(s) within its namespace, with each representation in
 103     the form of a sequence of bytes with a defined media type,
 104     character set, encoding, etc. Each resource may be associated
 105     with zero, one, or more than one representation at any given
 106     time. If multiple representations are available, the resource
 107     is referred to as <strong>negotiable</strong> and each of its
 108     representations is termed a <strong>variant</strong>. The ways
 109     in which the variants for a negotiable resource vary are called
 110     the <strong>dimensions</strong> of negotiation.</p>
 111 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 112 <div class="section">
 113 <h2><a name="negotiation" id="negotiation">Negotiation in httpd</a> <a title="Permanent link" href="#negotiation" class="permalink">&para;</a></h2>
 114
 115     <p>In order to negotiate a resource, the server needs to be
 116     given information about each of the variants. This is done in
 117     one of two ways:</p>
 118
 119     <ul>
 120       <li>Using a type map (<em>i.e.</em>, a <code>*.var</code>
 121       file) which names the files containing the variants
 122       explicitly, or</li>
 123
 124       <li>Using a 'MultiViews' search, where the server does an
 125       implicit filename pattern match and chooses from among the
 126       results.</li>
 127     </ul>
 128
 129    <h3><a name="type-map" id="type-map">Using a type-map file</a></h3>
 130
 131     <p>A type map is a document which is associated with the handler
 132     named <code>type-map</code> (or, for backwards-compatibility with
 133     older httpd configurations, the <a class="glossarylink" href="./glossary.html#mime-type" title="see glossary">MIME-type</a>
 134     <code>application/x-type-map</code>). Note that to use this
 135     feature, you must have a handler set in the configuration that
 136     defines a file suffix as <code>type-map</code>; this is best done
 137     with</p>
 138
 139     <pre class="prettyprint lang-config">AddHandler type-map .var</pre>
 140
 141
 142     <p>in the server configuration file.</p>
 143
 144     <p>Type map files should have the same name as the resource
 145     which they are describing, followed by the extension
 146     <code>.var</code>. In the examples shown below, the resource is
 147     named <code>foo</code>, so the type map file is named
 148     <code>foo.var</code>.</p>
 149
 150     <p>This file should have an entry for each available
 151     variant; these entries consist of contiguous HTTP-format header
 152     lines. Entries for different variants are separated by blank
 153     lines. Blank lines are illegal within an entry. It is
 154     conventional to begin a map file with an entry for the combined
 155     entity as a whole (although this is not required, and if
 156     present will be ignored). An example map file is shown below.</p>
 157
 158     <p>URIs in this file are relative to the location of the type map
 159     file. Usually, these files will be located in the same directory as
 160     the type map file, but this is not required. You may provide
 161     absolute or relative URIs for any file located on the same server as
 162     the map file.</p>
 163
 164 <div class="example"><p><code>
 165   URI: foo<br />
 166 <br />
 167   URI: foo.en.html<br />
 168   Content-type: text/html<br />
 169   Content-language: en<br />
 170 <br />
 171   URI: foo.fr.de.html<br />
 172   Content-type: text/html;charset=iso-8859-2<br />
 173   Content-language: fr, de<br />
 174 </code></p></div>
 175
 176     <p>Note also that a typemap file will take precedence over the
 177     filename's extension, even when Multiviews is on. If the
 178     variants have different source qualities, that may be indicated
 179     by the "qs" parameter to the media type, as in this picture
 180     (available as JPEG, GIF, or ASCII-art): </p>
 181
 182 <div class="example"><p><code>
 183   URI: foo<br />
 184 <br />
 185   URI: foo.jpeg<br />
 186   Content-type: image/jpeg; qs=0.8<br />
 187 <br />
 188   URI: foo.gif<br />
 189   Content-type: image/gif; qs=0.5<br />
 190 <br />
 191   URI: foo.txt<br />
 192   Content-type: text/plain; qs=0.01<br />
 193 </code></p></div>
 194
 195     <p>qs values can vary in the range 0.000 to 1.000. Note that
 196     any variant with a qs value of 0.000 will never be chosen.
 197     Variants with no 'qs' parameter value are given a qs factor of
 198     1.0. The qs parameter indicates the relative 'quality' of this
 199     variant compared to the other available variants, independent
 200     of the client's capabilities. For example, a JPEG file is
 201     usually of higher source quality than an ASCII file if it is
 202     attempting to represent a photograph. However, if the resource
 203     being represented is an original ASCII art, then an ASCII
 204     representation would have a higher source quality than a JPEG
 205     representation. A qs value is therefore specific to a given
 206     variant depending on the nature of the resource it
 207     represents.</p>
 208
 209     <p>The full list of headers recognized is available in the <a href="mod/mod_negotiation.html#typemaps">mod_negotiation
 210     typemap</a> documentation.</p>
 211
 212
 213 <h3><a name="multiviews" id="multiviews">Multiviews</a></h3>
 214
 215     <p><code>MultiViews</code> is a per-directory option, meaning it
 216     can be set with an <code class="directive"><a href="./mod/core.html#options">Options</a></code>
 217     directive within a <code class="directive"><a href="./mod/core.html#directory">&lt;Directory&gt;</a></code>, <code class="directive"><a href="./mod/core.html#location">&lt;Location&gt;</a></code> or <code class="directive"><a href="./mod/core.html#files">&lt;Files&gt;</a></code> section in
 218     <code>httpd.conf</code>, or (if <code class="directive"><a href="./mod/core.html#allowoverride">AllowOverride</a></code> is properly set) in
 219     <code>.htaccess</code> files. Note that <code>Options All</code>
 220     does not set <code>MultiViews</code>; you have to ask for it by
 221     name.</p>
 222
 223     <p>The effect of <code>MultiViews</code> is as follows: if the
 224     server receives a request for <code>/some/dir/foo</code>, if
 225     <code>/some/dir</code> has <code>MultiViews</code> enabled, and
 226     <code>/some/dir/foo</code> does <em>not</em> exist, then the
 227     server reads the directory looking for files named foo.*, and
 228     effectively fakes up a type map which names all those files,
 229     assigning them the same media types and content-encodings it
 230     would have if the client had asked for one of them by name. It
 231     then chooses the best match to the client's requirements.</p>
 232
 233     <p><code>MultiViews</code> may also apply to searches for the file
 234     named by the <code class="directive"><a href="./mod/mod_dir.html#directoryindex">DirectoryIndex</a></code> directive, if the
 235     server is trying to index a directory. If the configuration files
 236     specify</p>
 237     <pre class="prettyprint lang-config">DirectoryIndex index</pre>
 238
 239     <p>then the server will arbitrate between <code>index.html</code>
 240     and <code>index.html3</code> if both are present. If neither
 241     are present, and <code>index.cgi</code> is there, the server
 242     will run it.</p>
 243
 244     <p>If one of the files found when reading the directory does not
 245     have an extension recognized by <code>mod_mime</code> to designate
 246     its Charset, Content-Type, Language, or Encoding, then the result
 247     depends on the setting of the <code class="directive"><a href="./mod/mod_mime.html#multiviewsmatch">MultiViewsMatch</a></code> directive.  This
 248     directive determines whether handlers, filters, and other
 249     extension types can participate in MultiViews negotiation.</p>
 250
 251 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 252 <div class="section">
 253 <h2><a name="methods" id="methods">The Negotiation Methods</a> <a title="Permanent link" href="#methods" class="permalink">&para;</a></h2>
 254
 255     <p>After httpd has obtained a list of the variants for a given
 256     resource, either from a type-map file or from the filenames in
 257     the directory, it invokes one of two methods to decide on the
 258     'best' variant to return, if any. It is not necessary to know
 259     any of the details of how negotiation actually takes place in
 260     order to use httpd's content negotiation features. However the
 261     rest of this document explains the methods used for those
 262     interested. </p>
 263
 264     <p>There are two negotiation methods:</p>
 265
 266     <ol>
 267       <li><strong>Server driven negotiation with the httpd
 268       algorithm</strong> is used in the normal case. The httpd
 269       algorithm is explained in more detail below. When this
 270       algorithm is used, httpd can sometimes 'fiddle' the quality
 271       factor of a particular dimension to achieve a better result.
 272       The ways httpd can fiddle quality factors is explained in
 273       more detail below.</li>
 274
 275       <li><strong>Transparent content negotiation</strong> is used
 276       when the browser specifically requests this through the
 277       mechanism defined in RFC 2295. This negotiation method gives
 278       the browser full control over deciding on the 'best' variant,
 279       the result is therefore dependent on the specific algorithms
 280       used by the browser. As part of the transparent negotiation
 281       process, the browser can ask httpd to run the 'remote
 282       variant selection algorithm' defined in RFC 2296.</li>
 283     </ol>
 284
 285 <h3><a name="dimensions" id="dimensions">Dimensions of Negotiation</a></h3>
 286
 287     <table>
 288
 289       <tr valign="top">
 290         <th>Dimension</th>
 291
 292         <th>Notes</th>
 293       </tr>
 294
 295       <tr valign="top">
 296         <td>Media Type</td>
 297
 298         <td>Browser indicates preferences with the <code>Accept</code>
 299         header field. Each item can have an associated quality factor.
 300         Variant description can also have a quality factor (the "qs"
 301         parameter).</td>
 302       </tr>
 303
 304       <tr valign="top">
 305         <td>Language</td>
 306
 307         <td>Browser indicates preferences with the
 308         <code>Accept-Language</code> header field. Each item can have
 309         a quality factor. Variants can be associated with none, one or
 310         more than one language.</td>
 311       </tr>
 312
 313       <tr valign="top">
 314         <td>Encoding</td>
 315
 316         <td>Browser indicates preference with the
 317         <code>Accept-Encoding</code> header field. Each item can have
 318         a quality factor.</td>
 319       </tr>
 320
 321       <tr valign="top">
 322         <td>Charset</td>
 323
 324         <td>Browser indicates preference with the
 325         <code>Accept-Charset</code> header field. Each item can have a
 326         quality factor. Variants can indicate a charset as a parameter
 327         of the media type.</td>
 328       </tr>
 329     </table>
 330
 331
 332 <h3><a name="algorithm" id="algorithm">httpd Negotiation Algorithm</a></h3>
 333
 334     <p>httpd can use the following algorithm to select the 'best'
 335     variant (if any) to return to the browser. This algorithm is
 336     not further configurable. It operates as follows:</p>
 337
 338     <ol>
 339       <li>First, for each dimension of the negotiation, check the
 340       appropriate <em>Accept*</em> header field and assign a
 341       quality to each variant. If the <em>Accept*</em> header for
 342       any dimension implies that this variant is not acceptable,
 343       eliminate it. If no variants remain, go to step 4.</li>
 344
 345       <li>
 346         Select the 'best' variant by a process of elimination. Each
 347         of the following tests is applied in order. Any variants
 348         not selected at each test are eliminated. After each test,
 349         if only one variant remains, select it as the best match
 350         and proceed to step 3. If more than one variant remains,
 351         move on to the next test.
 352
 353         <ol>
 354           <li>Multiply the quality factor from the <code>Accept</code>
 355           header with the quality-of-source factor for this variants
 356           media type, and select the variants with the highest
 357           value.</li>
 358
 359           <li>Select the variants with the highest language quality
 360           factor.</li>
 361
 362           <li>Select the variants with the best language match,
 363           using either the order of languages in the
 364           <code>Accept-Language</code> header (if present), or else
 365           the order of languages in the <code>LanguagePriority</code>
 366           directive (if present).</li>
 367
 368           <li>Select the variants with the highest 'level' media
 369           parameter (used to give the version of text/html media
 370           types).</li>
 371
 372           <li>Select variants with the best charset media
 373           parameters, as given on the <code>Accept-Charset</code>
 374           header line.  Charset ISO-8859-1 is acceptable unless
 375           explicitly excluded. Variants with a <code>text/*</code>
 376           media type but not explicitly associated with a particular
 377           charset are assumed to be in ISO-8859-1.</li>
 378
 379           <li>Select those variants which have associated charset
 380           media parameters that are <em>not</em> ISO-8859-1. If
 381           there are no such variants, select all variants
 382           instead.</li>
 383
 384           <li>Select the variants with the best encoding. If there
 385           are variants with an encoding that is acceptable to the
 386           user-agent, select only these variants. Otherwise if
 387           there is a mix of encoded and non-encoded variants,
 388           select only the unencoded variants. If either all
 389           variants are encoded or all variants are not encoded,
 390           select all variants.</li>
 391
 392           <li>Select the variants with the smallest content
 393           length.</li>
 394
 395           <li>Select the first variant of those remaining. This
 396           will be either the first listed in the type-map file, or
 397           when variants are read from the directory, the one whose
 398           file name comes first when sorted using ASCII code
 399           order.</li>
 400         </ol>
 401       </li>
 402
 403       <li>The algorithm has now selected one 'best' variant, so
 404       return it as the response. The HTTP response header
 405       <code>Vary</code> is set to indicate the dimensions of
 406       negotiation (browsers and caches can use this information when
 407       caching the resource).  End.</li>
 408
 409       <li>To get here means no variant was selected (because none
 410       are acceptable to the browser). Return a 406 status (meaning
 411       "No acceptable representation") with a response body
 412       consisting of an HTML document listing the available
 413       variants. Also set the HTTP <code>Vary</code> header to
 414       indicate the dimensions of variance.</li>
 415     </ol>
 416
 417 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 418 <div class="section">
 419 <h2><a name="better" id="better">Fiddling with Quality
 420     Values</a> <a title="Permanent link" href="#better" class="permalink">&para;</a></h2>
 421
 422     <p>httpd sometimes changes the quality values from what would
 423     be expected by a strict interpretation of the httpd
 424     negotiation algorithm above. This is to get a better result
 425     from the algorithm for browsers which do not send full or
 426     accurate information. Some of the most popular browsers send
 427     <code>Accept</code> header information which would otherwise
 428     result in the selection of the wrong variant in many cases. If a
 429     browser sends full and correct information these fiddles will not
 430     be applied.</p>
 431
 432 <h3><a name="wildcards" id="wildcards">Media Types and Wildcards</a></h3>
 433
 434     <p>The <code>Accept:</code> request header indicates preferences
 435     for media types. It can also include 'wildcard' media types, such
 436     as "image/*" or "*/*" where the * matches any string. So a request
 437     including:</p>
 438
 439 <div class="example"><p><code>Accept: image/*, */*</code></p></div>
 440
 441     <p>would indicate that any type starting "image/" is acceptable,
 442     as is any other type.
 443     Some browsers routinely send wildcards in addition to explicit
 444     types they can handle. For example:</p>
 445
 446 <div class="example"><p><code>
 447   Accept: text/html, text/plain, image/gif, image/jpeg, */*
 448 </code></p></div>
 449     <p>The intention of this is to indicate that the explicitly listed
 450     types are preferred, but if a different representation is
 451     available, that is ok too.  Using explicit quality values,
 452     what the browser really wants is something like:</p>
 453 <div class="example"><p><code>
 454   Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01
 455 </code></p></div>
 456     <p>The explicit types have no quality factor, so they default to a
 457     preference of 1.0 (the highest). The wildcard */* is given a
 458     low preference of 0.01, so other types will only be returned if
 459     no variant matches an explicitly listed type.</p>
 460
 461     <p>If the <code>Accept:</code> header contains <em>no</em> q
 462     factors at all, httpd sets the q value of "*/*", if present, to
 463     0.01 to emulate the desired behavior. It also sets the q value of
 464     wildcards of the format "type/*" to 0.02 (so these are preferred
 465     over matches against "*/*". If any media type on the
 466     <code>Accept:</code> header contains a q factor, these special
 467     values are <em>not</em> applied, so requests from browsers which
 468     send the explicit information to start with work as expected.</p>
 469
 470
 471 <h3><a name="exceptions" id="exceptions">Language Negotiation Exceptions</a></h3>
 472
 473     <p>New in httpd 2.0, some exceptions have been added to the
 474     negotiation algorithm to allow graceful fallback when language
 475     negotiation fails to find a match.</p>
 476
 477     <p>When a client requests a page on your server, but the server
 478     cannot find a single page that matches the
 479     <code>Accept-language</code> sent by
 480     the browser, the server will return either a "No Acceptable
 481     Variant" or "Multiple Choices" response to the client.  To avoid
 482     these error messages, it is possible to configure httpd to ignore
 483     the <code>Accept-language</code> in these cases and provide a
 484     document that does not explicitly match the client's request.  The
 485     <code class="directive"><a href="./mod/mod_negotiation.html#forcelanguagepriority">ForceLanguagePriority</a></code>
 486     directive can be used to override one or both of these error
 487     messages and substitute the servers judgement in the form of the
 488     <code class="directive"><a href="./mod/mod_negotiation.html#languagepriority">LanguagePriority</a></code>
 489     directive.</p>
 490
 491     <p>The server will also attempt to match language-subsets when no
 492     other match can be found.  For example, if a client requests
 493     documents with the language <code>en-GB</code> for British
 494     English, the server is not normally allowed by the HTTP/1.1
 495     standard to match that against a document that is marked as simply
 496     <code>en</code>.  (Note that it is almost surely a configuration
 497     error to include <code>en-GB</code> and not <code>en</code> in the
 498     <code>Accept-Language</code> header, since it is very unlikely
 499     that a reader understands British English, but doesn't understand
 500     English in general.  Unfortunately, many current clients have
 501     default configurations that resemble this.)  However, if no other
 502     language match is possible and the server is about to return a "No
 503     Acceptable Variants" error or fallback to the <code class="directive"><a href="./mod/mod_negotiation.html#languagepriority">LanguagePriority</a></code>, the server
 504     will ignore the subset specification and match <code>en-GB</code>
 505     against <code>en</code> documents.  Implicitly, httpd will add
 506     the parent language to the client's acceptable language list with
 507     a very low quality value.  But note that if the client requests
 508     "en-GB; q=0.9, fr; q=0.8", and the server has documents
 509     designated "en" and "fr", then the "fr" document will be returned.
 510     This is necessary to maintain compliance with the HTTP/1.1
 511     specification and to work effectively with properly configured
 512     clients.</p>
 513
 514     <p>In order to support advanced techniques (such as cookies or
 515     special URL-paths) to determine the user's preferred language,
 516     since httpd 2.0.47 <code class="module"><a href="./mod/mod_negotiation.html">mod_negotiation</a></code> recognizes
 517     the <a href="env.html">environment variable</a>
 518     <code>prefer-language</code>. If it exists and contains an
 519     appropriate language tag, <code class="module"><a href="./mod/mod_negotiation.html">mod_negotiation</a></code> will
 520     try to select a matching variant. If there's no such variant,
 521     the normal negotiation process applies.</p>
 522
 523     <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SetEnvIf Cookie "language=(.+)" prefer-language=$1
 524 Header append Vary cookie</pre>
 525 </div>
 526
 527 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 528 <div class="section">
 529 <h2><a name="extensions" id="extensions">Extensions to Transparent Content
 530 Negotiation</a> <a title="Permanent link" href="#extensions" class="permalink">&para;</a></h2>
 531
 532 <p>httpd extends the transparent content negotiation protocol (RFC
 533 2295) as follows. A new <code>{encoding ..}</code> element is used in
 534 variant lists to label variants which are available with a specific
 535 content-encoding only. The implementation of the RVSA/1.0 algorithm
 536 (RFC 2296) is extended to recognize encoded variants in the list, and
 537 to use them as candidate variants whenever their encodings are
 538 acceptable according to the <code>Accept-Encoding</code> request
 539 header. The RVSA/1.0 implementation does not round computed quality
 540 factors to 5 decimal places before choosing the best variant.</p>
 541 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 542 <div class="section">
 543 <h2><a name="naming" id="naming">Note on hyperlinks and naming conventions</a> <a title="Permanent link" href="#naming" class="permalink">&para;</a></h2>
 544
 545     <p>If you are using language negotiation you can choose between
 546     different naming conventions, because files can have more than
 547     one extension, and the order of the extensions is normally
 548     irrelevant (see the <a href="mod/mod_mime.html#multipleext">mod_mime</a> documentation
 549     for details).</p>
 550
 551     <p>A typical file has a MIME-type extension (<em>e.g.</em>,
 552     <code>html</code>), maybe an encoding extension (<em>e.g.</em>,
 553     <code>gz</code>), and of course a language extension
 554     (<em>e.g.</em>, <code>en</code>) when we have different
 555     language variants of this file.</p>
 556
 557     <p>Examples:</p>
 558
 559     <ul>
 560       <li>foo.en.html</li>
 561
 562       <li>foo.html.en</li>
 563
 564       <li>foo.en.html.gz</li>
 565     </ul>
 566
 567     <p>Here some more examples of filenames together with valid and
 568     invalid hyperlinks:</p>
 569
 570     <table class="bordered">
 571
 572       <tr>
 573         <th>Filename</th>
 574
 575         <th>Valid hyperlink</th>
 576
 577         <th>Invalid hyperlink</th>
 578       </tr>
 579
 580       <tr>
 581         <td><em>foo.html.en</em></td>
 582
 583         <td>foo<br />
 584          foo.html</td>
 585
 586         <td>-</td>
 587       </tr>
 588
 589       <tr>
 590         <td><em>foo.en.html</em></td>
 591
 592         <td>foo</td>
 593
 594         <td>foo.html</td>
 595       </tr>
 596
 597       <tr>
 598         <td><em>foo.html.en.gz</em></td>
 599
 600         <td>foo<br />
 601          foo.html</td>
 602
 603         <td>foo.gz<br />
 604          foo.html.gz</td>
 605       </tr>
 606
 607       <tr>
 608         <td><em>foo.en.html.gz</em></td>
 609
 610         <td>foo</td>
 611
 612         <td>foo.html<br />
 613          foo.html.gz<br />
 614          foo.gz</td>
 615       </tr>
 616
 617       <tr>
 618         <td><em>foo.gz.html.en</em></td>
 619
 620         <td>foo<br />
 621          foo.gz<br />
 622          foo.gz.html</td>
 623
 624         <td>foo.html</td>
 625       </tr>
 626
 627       <tr>
 628         <td><em>foo.html.gz.en</em></td>
 629
 630         <td>foo<br />
 631          foo.html<br />
 632          foo.html.gz</td>
 633
 634         <td>foo.gz</td>
 635       </tr>
 636     </table>
 637
 638     <p>Looking at the table above, you will notice that it is always
 639     possible to use the name without any extensions in a hyperlink
 640     (<em>e.g.</em>, <code>foo</code>). The advantage is that you
 641     can hide the actual type of a document rsp. file and can change
 642     it later, <em>e.g.</em>, from <code>html</code> to
 643     <code>shtml</code> or <code>cgi</code> without changing any
 644     hyperlink references.</p>
 645
 646     <p>If you want to continue to use a MIME-type in your
 647     hyperlinks (<em>e.g.</em> <code>foo.html</code>) the language
 648     extension (including an encoding extension if there is one)
 649     must be on the right hand side of the MIME-type extension
 650     (<em>e.g.</em>, <code>foo.html.en</code>).</p>
 651 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 652 <div class="section">
 653 <h2><a name="caching" id="caching">Note on Caching</a> <a title="Permanent link" href="#caching" class="permalink">&para;</a></h2>
 654
 655     <p>When a cache stores a representation, it associates it with
 656     the request URL. The next time that URL is requested, the cache
 657     can use the stored representation. But, if the resource is
 658     negotiable at the server, this might result in only the first
 659     requested variant being cached and subsequent cache hits might
 660     return the wrong response. To prevent this, httpd normally
 661     marks all responses that are returned after content negotiation
 662     as non-cacheable by HTTP/1.0 clients. httpd also supports the
 663     HTTP/1.1 protocol features to allow caching of negotiated
 664     responses.</p>
 665
 666     <p>For requests which come from a HTTP/1.0 compliant client
 667     (either a browser or a cache), the directive <code class="directive"><a href="./mod/mod_negotiation.html#cachenegotiateddocs">CacheNegotiatedDocs</a></code> can be
 668     used to allow caching of responses which were subject to
 669     negotiation. This directive can be given in the server config or
 670     virtual host, and takes no arguments. It has no effect on requests
 671     from HTTP/1.1 clients.</p>
 672
 673     <p>For HTTP/1.1 clients, httpd sends a <code>Vary</code> HTTP
 674     response header to indicate the negotiation dimensions for the
 675     response.  Caches can use this information to determine whether a
 676     subsequent request can be served from the local copy.  To
 677     encourage a cache to use the local copy regardless of the
 678     negotiation dimensions, set the <code>force-no-vary</code> <a href="env.html#special">environment variable</a>.</p>
 679
 680 </div></div>
 681 <div class="bottomlang">
 682 <p><span>Available Languages: </span><a href="./en/content-negotiation.html" title="English">&nbsp;en&nbsp;</a> |
 683 <a href="./fr/content-negotiation.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a> |
 684 <a href="./ja/content-negotiation.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
 685 <a href="./ko/content-negotiation.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a> |
 686 <a href="./tr/content-negotiation.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</a></p>
 687 </div><div class="top"><a href="#page-header"><img src="./images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&amp;A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
 688 <script type="text/javascript"><!--//--><![CDATA[//><!--
 689 var comments_shortname = 'httpd';
 690 var comments_identifier = 'http://httpd.apache.org/docs/trunk/content-negotiation.html';
 691 (function(w, d) {
 692     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
 693         d.write('<div id="comments_thread"><\/div>');
 694         var s = d.createElement('script');
 695         s.type = 'text/javascript';
 696         s.async = true;
 697         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
 698         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
 699     }
 700     else {
 701         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
 702     }
 703 })(window, document);
 704 //--><!]]></script></div><div id="footer">
 705 <p class="apache">Copyright 2019 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 706 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
 707 if (typeof(prettyPrint) !== 'undefined') {
 708     prettyPrint();
 709 }
 710 //--><!]]></script>
 711 </body></html>