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

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <HTML>
   3 <HEAD>
   4 <TITLE>Apache Content Negotiation</TITLE>
   5 </HEAD>
   6
   7 <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
   8 <BODY
   9  BGCOLOR="#FFFFFF"
  10  TEXT="#000000"
  11  LINK="#0000FF"
  12  VLINK="#000080"
  13  ALINK="#FF0000"
  14 >
  15 <!--#include virtual="header.html" -->
  16 <h1 ALIGN="CENTER">Content Negotiation</H1>
  17
  18 <P>
  19 Apache's support for content negotiation has been updated to meet the
  20 HTTP/1.1 specification. It can choose the best representation of a
  21 resource based on the browser-supplied preferences for media type,
  22 languages, character set and encoding.  It is also implements a
  23 couple of features to give more intelligent handling of requests from
  24 browsers which send incomplete negotiation information.  <P>
  25
  26 Content negotiation is provided by the
  27 <A HREF="mod/mod_negotiation.html">mod_negotiation</A> module,
  28 which is compiled in by default.
  29
  30 <HR>
  31
  32 <h2>About Content Negotiation</h2>
  33
  34 <P>
  35 A resource may be available in several different representations. For
  36 example, it might be available in different languages or different
  37 media types, or a combination.  One way of selecting the most
  38 appropriate choice is to give the user an index page, and let them
  39 select. However it is often possible for the server to choose
  40 automatically. This works because browsers can send as part of each
  41 request information about what representations they prefer. For
  42 example, a browser could indicate that it would like to see
  43 information in French, if possible, else English will do. Browsers
  44 indicate their preferences by headers in the request. To request only
  45 French representations, the browser would send
  46
  47 <PRE>
  48   Accept-Language: fr
  49 </PRE>
  50
  51 <P>
  52 Note that this preference will only be applied when there is a choice
  53 of representations and they vary by language.
  54 <P>
  55
  56 As an example of a more complex request, this browser has been
  57 configured to accept French and English, but prefer French, and to
  58 accept various media types, preferring HTML over plain text or other
  59 text types, and preferring GIF or JPEG over other media types, but also
  60 allowing any other media type as a last resort:
  61
  62 <PRE>
  63   Accept-Language: fr; q=1.0, en; q=0.5
  64   Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6,
  65         image/jpeg; q=0.6, image/*; q=0.5, */*; q=0.1
  66 </PRE>
  67
  68 Apache 1.2 supports 'server driven' content negotiation, as defined in
  69 the HTTP/1.1 specification. It fully supports the Accept,
  70 Accept-Language, Accept-Charset and Accept-Encoding request headers.
  71 <P>
  72
  73 The terms used in content negotiation are: a <STRONG>resource</STRONG> is an
  74 item which can be requested of a server, which might be selected as
  75 the result of a content negotiation algorithm. If a resource is
  76 available in several formats, these are called <STRONG>representations</STRONG>
  77 or <STRONG>variants</STRONG>. The ways in which the variants for a particular
  78 resource vary are called the <STRONG>dimensions</STRONG> of negotiation.
  79
  80 <h2>Negotiation in Apache</h2>
  81
  82 <P>
  83 In order to negotiate a resource, the server needs to be given
  84 information about each of the variants. This is done in one of two
  85 ways:
  86
  87 <UL>
  88   <LI> Using a type map (i.e., a <CODE>*.var</CODE> file) which
  89        names the files containing the variants explicitly
  90   <LI> Or using a 'MultiViews' search, where the server does an implicit
  91        filename pattern match, and chooses from among the results.
  92 </UL>
  93
  94 <h3>Using a type-map file</h3>
  95
  96 <P>
  97 A type map is a document which is associated with the handler
  98 named <CODE>type-map</CODE> (or, for backwards-compatibility with
  99 older Apache configurations, the mime type
 100 <CODE>application/x-type-map</CODE>).  Note that to use this feature,
 101 you've got to have a <CODE>SetHandler</CODE> some place which defines a
 102 file suffix as <CODE>type-map</CODE>; this is best done with a
 103 <PRE>
 104
 105   AddHandler type-map var
 106
 107 </PRE>
 108 in <CODE>srm.conf</CODE>.  See comments in the sample config files for
 109 details. <P>
 110
 111 Type map files have an entry for each available variant; these entries
 112 consist of contiguous RFC822-format header lines.  Entries for
 113 different variants are separated by blank lines.  Blank lines are
 114 illegal within an entry.  It is conventional to begin a map file with
 115 an entry for the combined entity as a whole (although this
 116 is not required, and if present will be ignored). An example
 117 map file is:
 118 <PRE>
 119
 120   URI: foo
 121
 122   URI: foo.en.html
 123   Content-type: text/html
 124   Content-language: en
 125
 126   URI: foo.fr.de.html
 127   Content-type: text/html; charset=iso-8859-2
 128   Content-language: fr, de
 129 </PRE>
 130
 131 If the variants have different source qualities, that may be indicated
 132 by the "qs" parameter to the media type, as in this picture (available
 133 as jpeg, gif, or ASCII-art):
 134 <PRE>
 135   URI: foo
 136
 137   URI: foo.jpeg
 138   Content-type: image/jpeg; qs=0.8
 139
 140   URI: foo.gif
 141   Content-type: image/gif; qs=0.5
 142
 143   URI: foo.txt
 144   Content-type: text/plain; qs=0.01
 145
 146 </PRE>
 147 <P>
 148
 149 qs values can vary between 0.000 and 1.000. Note that any variant with
 150 a qs value of 0.000 will never be chosen. Variants with no 'qs'
 151 parameter value are given a qs factor of 1.0.  <P>
 152
 153 The full list of headers recognized is:
 154
 155 <DL>
 156   <DT> <CODE>URI:</CODE>
 157   <DD> uri of the file containing the variant (of the given media
 158        type, encoded with the given content encoding).  These are
 159        interpreted as URLs relative to the map file; they must be on
 160        the same server (!), and they must refer to files to which the
 161        client would be granted access if they were to be requested
 162        directly.
 163   <DT> <CODE>Content-type:</CODE>
 164   <DD> media type --- charset, level and "qs" parameters may be given.  These
 165        are often referred to as MIME types; typical media types are
 166        <CODE>image/gif</CODE>, <CODE>text/plain</CODE>, or
 167        <CODE>text/html;&nbsp;level=3</CODE>.
 168   <DT> <CODE>Content-language:</CODE>
 169   <DD> The languages of the variant, specified as an Internet standard
 170        language code (e.g., <CODE>en</CODE> for English,
 171        <CODE>kr</CODE> for Korean, etc.).
 172   <DT> <CODE>Content-encoding:</CODE>
 173   <DD> If the file is compressed, or otherwise encoded, rather than
 174        containing the actual raw data, this says how that was done.
 175        For compressed files (the only case where this generally comes
 176        up), content encoding should be
 177        <CODE>x-compress</CODE>, or <CODE>x-gzip</CODE>, as appropriate.
 178   <DT> <CODE>Content-length:</CODE>
 179   <DD> The size of the file.  Clients can ask to receive a given media
 180        type only if the variant isn't too big; specifying a content
 181        length in the map allows the server to compare against these
 182        thresholds without checking the actual file.
 183 </DL>
 184
 185 <h3>Multiviews</h3>
 186
 187 <P>
 188 This is a per-directory option, meaning it can be set with an
 189 <CODE>Options</CODE> directive within a <CODE>&lt;Directory&gt;</CODE>,
 190 <CODE>&lt;Location&gt;</CODE> or <CODE>&lt;Files&gt;</CODE>
 191 section in <CODE>access.conf</CODE>, or (if <CODE>AllowOverride</CODE>
 192 is properly set) in <CODE>.htaccess</CODE> files.  Note that
 193 <CODE>Options All</CODE> does not set <CODE>MultiViews</CODE>; you
 194 have to ask for it by name.  (Fixing this is a one-line change to
 195 <CODE>http_core.h</CODE>).
 196
 197 <P>
 198
 199 The effect of <CODE>MultiViews</CODE> is as follows: if the server
 200 receives a request for <CODE>/some/dir/foo</CODE>, if
 201 <CODE>/some/dir</CODE> has <CODE>MultiViews</CODE> enabled, and
 202 <CODE>/some/dir/foo</CODE> does <EM>not</EM> exist, then the server reads the
 203 directory looking for files named foo.*, and effectively fakes up a
 204 type map which names all those files, assigning them the same media
 205 types and content-encodings it would have if the client had asked for
 206 one of them by name.  It then chooses the best match to the client's
 207 requirements, and forwards them along.
 208
 209 <P>
 210
 211 This applies to searches for the file named by the
 212 <CODE>DirectoryIndex</CODE> directive, if the server is trying to
 213 index a directory; if the configuration files specify
 214 <PRE>
 215
 216   DirectoryIndex index
 217
 218 </PRE> then the server will arbitrate between <CODE>index.html</CODE>
 219 and <CODE>index.html3</CODE> if both are present.  If neither are
 220 present, and <CODE>index.cgi</CODE> is there, the server will run it.
 221
 222 <P>
 223
 224 If one of the files found when reading the directive is a CGI script,
 225 it's not obvious what should happen.  The code gives that case
 226 special treatment --- if the request was a POST, or a GET with
 227 QUERY_ARGS or PATH_INFO, the script is given an extremely high quality
 228 rating, and generally invoked; otherwise it is given an extremely low
 229 quality rating, which generally causes one of the other views (if any)
 230 to be retrieved.
 231
 232 <h2>The Negotiation Algorithm</h2>
 233
 234 After Apache has obtained a list of the variants for a given resource,
 235 either from a type-map file or from the filenames in the directory, it
 236 applies a algorithm to decide on the 'best' variant to return, if
 237 any. To do this it calculates a quality value for each variant in each
 238 of the dimensions of variance. It is not necessary to know any of the
 239 details of how negotiation actually takes place in order to use Apache's
 240 content negotiation features. However the rest of this document
 241 explains in detail the algorithm used for those interested.  <P>
 242
 243 In some circumstances, Apache can 'fiddle' the quality factor of a
 244 particular dimension to achieve a better result. The ways Apache can
 245 fiddle quality factors is explained in more detail below.
 246
 247 <h3>Dimensions of Negotiation</h3>
 248
 249 <TABLE>
 250 <TR><TH>Dimension
 251 <TH>Notes
 252 <TR><TD>Media Type
 253 <TD>Browser indicates preferences on Accept: header. Each item
 254 can have an associated quality factor. Variant description can also
 255 have a quality factor.
 256 <TR><TD>Language
 257 <TD>Browser indicates preferences on Accept-Language: header. Each
 258 item
 259 can have a quality factor. Variants can be associated with none, one
 260 or more languages.
 261 <TR><TD>Encoding
 262 <TD>Browser indicates preference with Accept-Encoding: header.
 263 <TR><TD>Charset
 264 <TD>Browser indicates preference with Accept-Charset: header. Variants
 265 can indicate a charset as a parameter of the media type.
 266 </TABLE>
 267
 268 <h3>Apache Negotiation Algorithm</h3>
 269
 270 <P>
 271 Apache uses an algorithm to select the 'best' variant (if any) to
 272 return to the browser. This algorithm is not configurable. It operates
 273 like this:
 274
 275 <OL>
 276 <LI>
 277 Firstly, for each dimension of the negotiation, the appropriate
 278 Accept header is checked and a quality assigned to this each
 279 variant. If the Accept header for any dimension means that this
 280 variant is not acceptable, eliminate it. If no variants remain, go
 281 to step 4.
 282
 283 <LI>Select the 'best' variant by a process of elimination. Each of
 284 the following tests is applied in order. Any variants not selected at
 285 each stage are eliminated. After each test, if only one variant
 286 remains, it is selected as the best match. If more than one variant
 287 remains, move onto the next test.
 288
 289 <OL>
 290 <LI>Multiply the quality factor from the Accept header with the
 291   quality-of-source factor for this variant's media type, and select
 292   the variants with the highest value
 293
 294 <LI>Select the variants with the highest language quality factor
 295
 296 <LI>Select the variants with the best language match, using either the
 297   order of languages on the <CODE>LanguagePriority</CODE> directive (if present),
 298   else the order of languages on the Accept-Language header.
 299
 300 <LI>Select the variants with the highest 'level' media parameter
 301   (used to give the version of text/html media types).
 302
 303 <LI>Select only unencoded variants, if there is a mix of encoded
 304   and non-encoded variants. If either all variants are encoded
 305   or all variants are not encoded, select all.
 306
 307 <LI>Select only variants with acceptable charset media parameters,
 308   as given on the Accept-Charset header line. Charset ISO-8859-1
 309   is always acceptable. Variants not associated with a particular
 310   charset are assumed to be in ISO-8859-1.
 311
 312 <LI>Select the variants with the smallest content length
 313
 314 <LI>Select the first variant of those remaining (this will be either the
 315 first listed in the type-map file, or the first read from the directory)
 316 and go to stage 3.
 317
 318 </OL>
 319
 320 <LI>The algorithm has now selected one 'best' variant, so return
 321   it as the response. The HTTP response header Vary is set to indicate the
 322   dimensions of negotiation (browsers and caches can use this
 323   information when caching the resource). End.
 324
 325 <LI>To get here means no variant was selected (because non are acceptable
 326   to the browser). Return a 406 status (meaning "No acceptable representation")
 327   with a response body consisting of an HTML document listing the
 328   available variants. Also set the HTTP Vary header to indicate the
 329   dimensions of variance.
 330
 331 </OL>
 332
 333 <h2><A name="better">Fiddling with Quality Values</A></h2>
 334
 335 <P>
 336 Apache sometimes changes the quality values from what would be
 337 expected by a strict interpretation of the algorithm above. This is to
 338 get a better result from the algorithm for browsers which do not send
 339 full or accurate information. Some of the most popular browsers send
 340 Accept header information which would otherwise result in the
 341 selection of the wrong variant in many cases. If a browser
 342 sends full and correct information these fiddles will not
 343 be applied.
 344 <P>
 345
 346 <h3>Media Types and Wildcards</h3>
 347
 348 <P>
 349 The Accept: request header indicates preferences for media types. It
 350 can also include 'wildcard' media types, such as "image/*" or "*/*"
 351 where the * matches any string. So a request including:
 352 <PRE>
 353   Accept: image/*, */*
 354 </PRE>
 355
 356 would indicate that any type starting "image/" is acceptable,
 357 as is any other type (so the first "image/*" is redundant). Some
 358 browsers routinely send wildcards in addition to explicit types they
 359 can handle. For example:
 360 <PRE>
 361   Accept: text/html, text/plain, image/gif, image/jpeg, */*
 362 </PRE>
 363
 364 The intention of this is to indicate that the explicitly
 365 listed types are preferred, but if a different representation is
 366 available, that is ok too. However under the basic algorithm, as given
 367 above, the */* wildcard has exactly equal preference to all the other
 368 types, so they are not being preferred. The browser should really have
 369 sent a request with a lower quality (preference) value for *.*, such
 370 as:
 371 <PRE>
 372   Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01
 373 </PRE>
 374
 375 The explicit types have no quality factor, so they default to a
 376 preference of 1.0 (the highest). The wildcard */* is given
 377 a low preference of 0.01, so other types will only be returned if
 378 no variant matches an explicitly listed type.
 379 <P>
 380
 381 If the Accept: header contains <EM>no</EM> q factors at all, Apache sets
 382 the q value of "*/*", if present, to 0.01 to emulate the desired
 383 behavior. It also sets the q value of wildcards of the format
 384 "type/*" to 0.02 (so these are preferred over matches against
 385 "*/*". If any media type on the Accept: header contains a q factor,
 386 these special values are <EM>not</EM> applied, so requests from browsers
 387 which send the correct information to start with work as expected.
 388
 389 <h3>Variants with no Language</h3>
 390
 391 <P>
 392 If some of the variants for a particular resource have a language
 393 attribute, and some do not, those variants with no language
 394 are given a very low language quality factor of 0.001.<P>
 395
 396 The reason for setting this language quality factor for
 397 variant with no language to a very low value is to allow
 398 for a default variant which can be supplied if none of the
 399 other variants match the browser's language preferences.
 400
 401 For example, consider the situation with three variants:
 402
 403 <UL>
 404 <LI>foo.en.html, language en
 405 <LI>foo.fr.html, language en
 406 <LI>foo.html, no language
 407 </UL>
 408
 409 <P>
 410 The meaning of a variant with no language is that it is
 411 always acceptable to the browser. If the request Accept-Language
 412 header includes either en or fr (or both) one of foo.en.html
 413 or foo.fr.html will be returned. If the browser does not list
 414 either en or fr as acceptable, foo.html will be returned instead.
 415
 416 <h2>Note on hyperlinks and naming conventions</h2>
 417
 418 <P>
 419 If you are using language negotiation you can choose between
 420 different naming conventions, because files can have more than one
 421 extension, and the order of the extensions is normally irrelevant
 422 (see <A HREF="mod/mod_mime.html">mod_mime</A> documentation for details).
 423 <P>
 424 A typical file has a mime-type extension (e.g. <SAMP>html</SAMP>),
 425 maybe an encoding extension (e.g. <SAMP>gz</SAMP> and of course a
 426 language extension (e.g. <SAMP>en</SAMP>) when we have different
 427 language variants of this file.
 428
 429 <P>
 430 Examples:
 431 <UL>
 432 <LI>foo.en.html
 433 <LI>foo.html.en
 434 <LI>foo.en.html.gz
 435 </UL>
 436
 437 <P>
 438 Here some more examples of filenames together with valid and invalid hyperlinks:
 439 </P>
 440
 441 <table border=1 cellpadding=8 cellspacing=0>
 442 <TR>
 443  <TH>Filename</TH>
 444  <TH>Valid hyperlink</TH>
 445  <TH>Invalid hyperlink</TH>
 446 </TR>
 447 <TR>
 448  <TD><EM>foo.html.en</EM></TD>
 449  <TD>foo<BR>
 450      foo.html</TD>
 451  <TD>-</TD>
 452 </TR>
 453 <TR>
 454  <TD><EM>foo.en.html</EM></TD>
 455  <TD>foo</TD>
 456  <TD>foo.html</TD>
 457 </TR>
 458 <TR>
 459  <TD><EM>foo.html.en.gz</EM></TD>
 460  <TD>foo<BR>
 461      foo.html</TD>
 462  <TD>foo.gz<BR>
 463      foo.html.gz</TD>
 464 </TR>
 465 <TR>
 466  <TD><EM>foo.en.html.gz</EM></TD>
 467  <TD>foo</TD>
 468  <TD>foo.html<BR>
 469      foo.html.gz<BR>
 470      foo.gz</TD>
 471 </TR>
 472 <TR>
 473  <TD><EM>foo.gz.html.en</EM></TD>
 474  <TD>foo<BR>
 475      foo.gz<BR>
 476      foo.gz.html</TD>
 477  <TD>foo.html</TD>
 478 </TR>
 479 <TR>
 480  <TD><EM>foo.html.gz.en</EM></TD>
 481  <TD>foo<BR>
 482      foo.html<BR>
 483      foo.html.gz</TD>
 484  <TD>foo.gz</TD>
 485 </TR>
 486 </TABLE>
 487
 488 <P>
 489 Looking at the table above you will notice that it is always possible to
 490 use the name without any extensions  in an hyperlink (e.g. <SAMP>foo</SAMP>).
 491 The advantage is that you can hide the actual type of a
 492 document rsp. file and can change it later, e.g. from <SAMP>html</SAMP>
 493 to <SAMP>shtml</SAMP> or <SAMP>cgi</SAMP> without changing any
 494 hyperlink references.
 495
 496 <P>
 497 If you want to continue to use a mime-type in your hyperlinks (e.g.
 498 <SAMP>foo.html</SAMP>) the language extension (including an encoding extension
 499 if there is one) must be on the right hand side of the mime-type extension
 500 (e.g. <SAMP>foo.html.en</SAMP>).
 501
 502
 503 <h2>Note on Caching</h2>
 504
 505 <P>
 506 When a cache stores a document, it associates it with the request URL.
 507 The next time that URL is requested, the cache can use the stored
 508 document, provided it is still within date. But if the resource is
 509 subject to content negotiation at the server, this would result in
 510 only the first requested variant being cached, and subsequent cache
 511 hits could return the wrong response. To prevent this,
 512 Apache normally marks all responses that are returned after content negotiation
 513 as non-cacheable by HTTP/1.0 clients. Apache also supports the HTTP/1.1
 514 protocol features to allow caching of negotiated responses. <P>
 515
 516 For requests which come from a HTTP/1.0 compliant client (either a
 517 browser or a cache), the directive <TT>CacheNegotiatedDocs</TT> can be
 518 used to allow caching of responses which were subject to negotiation.
 519 This directive can be given in the server config or virtual host, and
 520 takes no arguments. It has no effect on requests from HTTP/1.1
 521 clients.
 522
 523 <!--#include virtual="footer.html" -->
 524 </BODY>
 525 </HTML>