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