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