content-negotiation.html revision db81e057b060e365d840d9a1d35a5797192efa81
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce BGCOLOR="#FFFFFF"
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce TEXT="#000000"
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce LINK="#0000FF"
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce VLINK="#000080"
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce ALINK="#FF0000"
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce<!--#include virtual="header.html" -->
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo SorceApache's support for content negotiation has been updated to meet the
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo SorceHTTP/1.1 specification. It can choose the best representation of a
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceresource based on the browser-supplied preferences for media type,
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcelanguages, character set and encoding. It is also implements a
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcecouple of features to give more intelligent handling of requests from
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorcebrowsers which send incomplete negotiation information. <p>
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo SorceContent negotiation is provided by the
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce<a href="mod/mod_negotiation.html">mod_negotiation</a> module,
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorcewhich is compiled in by default.
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo SorceA resource may be available in several different representations. For
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorceexample, it might be available in different languages or different
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorcemedia types, or a combination. One way of selecting the most
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorceappropriate choice is to give the user an index page, and let them
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorceselect. However it is often possible for the server to choose
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorceautomatically. This works because browsers can send as part of each
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorcerequest information about what representations they prefer. For
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorceexample, a browser could indicate that it would like to see
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorceinformation in French, if possible, else English will do. Browsers
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorceindicate their preferences by headers in the request. To request only
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo SorceFrench representations, the browser would send
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorce Accept-Language: fr
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo SorceNote that this preference will only be applied when there is a choice
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorceof representations and they vary by language.
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo SorceAs an example of a more complex request, this browser has been
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorceconfigured to accept French and English, but prefer French, and to
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorceaccept various media types, preferring HTML over plain text or other
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorcetext types, and preferring GIF or JPEG over other media types, but also
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorceallowing any other media type as a last resort:
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorce Accept-Language: fr; q=1.0, en; q=0.5
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorce Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6,
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo SorceApache 1.2 supports 'server driven' content negotiation, as defined in
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorcethe HTTP/1.1 specification. It fully supports the Accept,
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo SorceAccept-Language, Accept-Charset and Accept-Encoding request headers.
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo SorceThe terms used in content negotiation are: a <b>resource</b> is an
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorceitem which can be requested of a server, which might be selected as
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorcethe result of a content negotiation algorithm. If a resource is
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorceavailable in several formats, these are called <b>representations</b>
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorceor <b>variants</b>. The ways in which the variants for a particular
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorceresource vary are called the <b>dimensions</b> of negotiation.
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo SorceIn order to negotiate a resource, the server needs to be given
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorceinformation about each of the variants. This is done in one of two
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorce <li> Using a type map (i.e., a <code>*.var</code> file) which
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorce names the files containing the variants explicitly
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorce <li> Or using a 'MultiViews' search, where the server does an implicit
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorce filename pattern match, and chooses from among the results.
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo SorceA type map is a document which is associated with the handler
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcenamed <code>type-map</code> (or, for backwards-compatibility with
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceolder Apache configurations, the mime type
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce<code>application/x-type-map</code>). Note that to use this feature,
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceyou've got to have a <code>SetHandler</code> some place which defines a
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcefile suffix as <code>type-map</code>; this is best done with a
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce AddHandler type-map var
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcein <code>srm.conf</code>. See comments in the sample config files for
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo SorceType map files have an entry for each available variant; these entries
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceconsist of contiguous RFC822-format header lines. Entries for
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcedifferent variants are separated by blank lines. Blank lines are
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceillegal within an entry. It is conventional to begin a map file with
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcean entry for the combined entity as a whole (although this
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceis not required, and if present will be ignored). An example
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce Content-language: en
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce Content-language: fr, de
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo SorceIf the variants have different source qualities, that may be indicated
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceby the "qs" parameter to the media type, as in this picture (available
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceas jpeg, gif, or ASCII-art):
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceqs values can vary between 0.000 and 1.000. Note that any variant with
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcea qs value of 0.000 will never be chosen. Variants with no 'qs'
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceparameter value are given a qs factor of 1.0. <p>
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo SorceThe full list of headers recognized is:
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce <dd> uri of the file containing the variant (of the given media
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce type, encoded with the given content encoding). These are
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce interpreted as URLs relative to the map file; they must be on
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce the same server (!), and they must refer to files to which the
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce client would be granted access if they were to be requested
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce <dd> media type --- charset, level and "qs" parameters may be given. These
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce are often referred to as MIME types; typical media types are
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce <code>image/gif</code>, <code>text/plain</code>, or
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce <dd> The languages of the variant, specified as an Internet standard
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce language code (e.g., <code>en</code> for English,
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce <dd> If the file is compressed, or otherwise encoded, rather than
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce containing the actual raw data, this says how that was done.
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce For compressed files (the only case where this generally comes
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce up), content encoding should be
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce <code>x-compress</code>, or <code>x-gzip</code>, as appropriate.
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce <dd> The size of the file. Clients can ask to receive a given media
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce type only if the variant isn't too big; specifying a content
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce length in the map allows the server to compare against these
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce thresholds without checking the actual file.
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo SorceThis is a per-directory option, meaning it can be set with an
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce<code>Options</code> directive within a <code><Directory></code>,
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce<code><Location></code> or <code><Files></code>
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcesection in <code>access.conf</code>, or (if <code>AllowOverride</code>
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceis properly set) in <code>.htaccess</code> files. Note that
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce<code>Options All</code> does not set <code>MultiViews</code>; you
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorcehave to ask for it by name. (Fixing this is a one-line change to
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo SorceThe effect of <code>MultiViews</code> is as follows: if the server
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcereceives a request for <code>/some/dir/foo</code>, if
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce<code>/some/dir</code> has <code>MultiViews</code> enabled, and
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce<code>/some/dir/foo</code> does <em>not</em> exist, then the server reads the
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcedirectory looking for files named foo.*, and effectively fakes up a
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcetype map which names all those files, assigning them the same media
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcetypes and content-encodings it would have if the client had asked for
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceone of them by name. It then chooses the best match to the client's
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcerequirements, and forwards them along.
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo SorceThis applies to searches for the file named by the
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce<code>DirectoryIndex</code> directive, if the server is trying to
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceindex a directory; if the configuration files specify
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce DirectoryIndex index
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce</pre> then the server will arbitrate between <code>index.html</code>
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceand <code>index.html3</code> if both are present. If neither are
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcepresent, and <code>index.cgi</code> is there, the server will run it.
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo SorceIf one of the files found when reading the directive is a CGI script,
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorceit's not obvious what should happen. The code gives that case
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorcespecial treatment --- if the request was a POST, or a GET with
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo SorceQUERY_ARGS or PATH_INFO, the script is given an extremely high quality
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorcerating, and generally invoked; otherwise it is given an extremely low
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcequality rating, which generally causes one of the other views (if any)
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceto be retrieved.
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo SorceAfter Apache has obtained a list of the variants for a given resource,
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceeither from a type-map file or from the filenames in the directory, it
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceapplies a algorithm to decide on the 'best' variant to return, if
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorceany. To do this it calculates a quality value for each variant in each
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceof the dimensions of variance. It is not necessary to know any of the
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcedetails of how negotiation actually takes place in order to use Apache's
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcecontent negotiation features. However the rest of this document
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceexplains in detail the algorithm used for those interested. <p>
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo SorceIn some circumstances, Apache can 'fiddle' the quality factor of a
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceparticular dimension to achieve a better result. The ways Apache can
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcefiddle quality factors is explained in more detail below.
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce<td>Browser indicates preferences on Accept: header. Each item
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcecan have an associated quality factor. Variant description can also
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorcehave a quality factor.
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce<td>Browser indicates preferences on Accept-Language: header. Each
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcecan have a quality factor. Variants can be associated with none, one
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceor more languages.
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce<td>Browser indicates preference with Accept-Encoding: header.
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce<td>Browser indicates preference with Accept-Charset: header. Variants
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcecan indicate a charset as a parameter of the media type.
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo SorceApache uses an algorithm to select the 'best' variant (if any) to
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcereturn to the browser. This algorithm is not configurable. It operates
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo SorceFirstly, for each dimension of the negotiation, the appropriate
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo SorceAccept header is checked and a quality assigned to this each
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcevariant. If the Accept header for any dimension means that this
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcevariant is not acceptable, eliminate it. If no variants remain, go
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce<li>Select the 'best' variant by a process of elimination. Each of
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcethe following tests is applied in order. Any variants not selected at
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceeach stage are eliminated. After each test, if only one variant
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceremains, it is selected as the best match. If more than one variant
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceremains, move onto the next test.
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce<li>Multiply the quality factor from the Accept header with the
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce quality-of-source factor for this variant's media type, and select
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce the variants with the highest value
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce<li>Select the variants with the highest language quality factor
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce<li>Select the variants with the best language match, using either the
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce order of languages on the <code>LanguagePriority</code> directive (if present),
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce else the order of languages on the Accept-Language header.
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce<li>Select the variants with the highest 'level' media parameter
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce (used to give the version of text/html media types).
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce<li>Select only unencoded variants, if there is a mix of encoded
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce and non-encoded variants. If either all variants are encoded
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce or all variants are not encoded, select all.
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce<li>Select only variants with acceptable charset media parameters,
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce as given on the Accept-Charset header line. Charset ISO-8859-1
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce is always acceptable. Variants not associated with a particular
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce charset are assumed to be in ISO-8859-1.
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce<li>Select the variants with the smallest content length
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce<li>Select the first variant of those remaining (this will be either the
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorcefirst listed in the type-map file, or the first read from the directory)
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorceand go to stage 3.
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce<li>The algorithm has now selected one 'best' variant, so return
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce it as the response. The HTTP response header Vary is set to indicate the
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce dimensions of negotiation (browsers and caches can use this
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce information when caching the resource). End.
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorce<li>To get here means no variant was selected (because non are acceptable
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce to the browser). Return a 406 status (meaning "No acceptable representation")
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce with a response body consisting of an HTML document listing the
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce available variants. Also set the HTTP Vary header to indicate the
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce dimensions of variance.
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce<h2><a name="better">Fiddling with Quality Values</a></h2>
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo SorceApache sometimes changes the quality values from what would be
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceexpected by a strict interpretation of the algorithm above. This is to
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceget a better result from the algorithm for browsers which do not send
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcefull or accurate information. Some of the most popular browsers send
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo SorceAccept header information which would otherwise result in the
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceselection of the wrong variant in many cases. If a browser
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorcesends full and correct information these fiddles will not
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo SorceThe Accept: request header indicates preferences for media types. It
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorcecan also include 'wildcard' media types, such as "image/*" or "*/*"
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcewhere the * matches any string. So a request including:
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce Accept: image/*, */*
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorcewould indicate that any type starting "image/" is acceptable,
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorceas is any other type (so the first "image/*" is redundant). Some
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorcebrowsers routinely send wildcards in addition to explicit types they
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorcecan handle. For example:
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce Accept: text/html, text/plain, image/gif, image/jpeg, */*
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo SorceThe intention of this is to indicate that the explicitly
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorcelisted types are preferred, but if a different representation is
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceavailable, that is ok too. However under the basic algorithm, as given
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceabove, the */* wildcard has exactly equal preference to all the other
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcetypes, so they are not being preferred. The browser should really have
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcesent a request with a lower quality (preference) value for *.*, such
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo SorceThe explicit types have no quality factor, so they default to a
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcepreference of 1.0 (the highest). The wildcard */* is given
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcea low preference of 0.01, so other types will only be returned if
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceno variant matches an explicitly listed type.
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo SorceIf the Accept: header contains <i>no</i> q factors at all, Apache sets
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcethe q value of "*/*", if present, to 0.01 to emulate the desired
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcebehavior. It also sets the q value of wildcards of the format
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce"type/*" to 0.02 (so these are preferred over matches against
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorce"*/*". If any media type on the Accept: header contains a q factor,
625bb2ddf15e8f305a53afa44e87f2146fa930afSimo Sorcethese special values are <i>not</i> applied, so requests from browsers
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcewhich send the correct information to start with work as expected.
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo SorceIf some of the variants for a particular resource have a language
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceattribute, and some do not, those variants with no language
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorceare given a very low language quality factor of 0.001.<p>
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo SorceThe reason for setting this language quality factor for
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcevariant with no language to a very low value is to allow
1dd679584241a0f9b29072c7eed1c5c5e4a577e4Simo Sorcefor a default variant which can be supplied if none of the
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorceother variants match the browser's language preferences.
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo SorceFor example, consider the situation with three variants:
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo SorceThe meaning of a variant with no language is that it is
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorcealways acceptable to the browser. If the request Accept-Language
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorceheader includes either en or fr (or both) one of foo.en.html
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorceor foo.fr.html will be returned. If the browser does not list
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorceeither en or fr as acceptable, foo.html will be returned instead.
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo SorceWhen a cache stores a document, it associates it with the request URL.
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo SorceThe next time that URL is requested, the cache can use the stored
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorcedocument, provided it is still within date. But if the resource is
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorcesubject to content negotiation at the server, this would result in
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorceonly the first requested variant being cached, and subsequent cache
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorcehits could return the wrong response. To prevent this,
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo SorceApache normally marks all responses that are returned after content negotiation
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorceas non-cacheable by HTTP/1.0 clients. Apache also supports the HTTP/1.1
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorceprotocol features to allow caching of negotiated responses. <P>
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo SorceFor requests which come from a HTTP/1.0 compliant client (either a
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorcebrowser or a cache), the directive <tt>CacheNegotiatedDocs</tt> can be
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorceused to allow caching of responses which were subject to negotiation.
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo SorceThis directive can be given in the server config or virtual host, and
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorcetakes no arguments. It has no effect on requests from HTTP/1.1
a9d46b86993ee8d87fddf0ba50665c0b1b78ebb7Simo Sorce<!--#include virtual="footer.html" -->