content-negotiation.html revision bf3d9f591e5af24fdcaa9029094dc045878d1d1a
52ea316008e2581c8113441c9c341e5c65225f6anilgun<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
52ea316008e2581c8113441c9c341e5c65225f6anilgun<HTML>
52ea316008e2581c8113441c9c341e5c65225f6anilgun<HEAD>
52ea316008e2581c8113441c9c341e5c65225f6anilgun<TITLE>Apache Content Negotiation</TITLE>
52ea316008e2581c8113441c9c341e5c65225f6anilgun</HEAD>
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgun<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
52ea316008e2581c8113441c9c341e5c65225f6anilgun<BODY
52ea316008e2581c8113441c9c341e5c65225f6anilgun BGCOLOR="#FFFFFF"
52ea316008e2581c8113441c9c341e5c65225f6anilgun TEXT="#000000"
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen LINK="#0000FF"
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen VLINK="#000080"
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen ALINK="#FF0000"
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen>
52ea316008e2581c8113441c9c341e5c65225f6anilgun<!--#include virtual="header.html" -->
52ea316008e2581c8113441c9c341e5c65225f6anilgun<h1 ALIGN="CENTER">Content Negotiation</h1>
d229f940abfb2490dee17979e9a5ff31b7012eb5rbowen
3f08db06526d6901aa08c110b5bc7dde6bc39905ndApache's support for content negotiation has been updated to meet the
52ea316008e2581c8113441c9c341e5c65225f6anilgunHTTP/1.1 specification. It can choose the best representation of a
52ea316008e2581c8113441c9c341e5c65225f6anilgunresource based on the browser-supplied preferences for media type,
52ea316008e2581c8113441c9c341e5c65225f6anilgunlanguages, character set and encoding. It is also implements a
3f08db06526d6901aa08c110b5bc7dde6bc39905ndcouple of features to give more intelligent handling of requests from
52ea316008e2581c8113441c9c341e5c65225f6anilgunbrowsers which send incomplete negotiation information. <p>
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgunContent negotiation is provided by the
52ea316008e2581c8113441c9c341e5c65225f6anilgun<a href="mod/mod_negotiation.html">mod_negotiation</a> module,
52ea316008e2581c8113441c9c341e5c65225f6anilgunwhich is compiled in by default.
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung
52ea316008e2581c8113441c9c341e5c65225f6anilgun<hr>
51b60896224b408a35684bd6ec0fafe5e4abe322rbowen
52ea316008e2581c8113441c9c341e5c65225f6anilgun<h2>About Content Negotiation</h2>
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgunA resource may be available in several different representations. For
52ea316008e2581c8113441c9c341e5c65225f6anilgunexample, it might be available in different languages or different
52ea316008e2581c8113441c9c341e5c65225f6anilgunmedia types, or a combination. One way of selecting the most
52ea316008e2581c8113441c9c341e5c65225f6anilgunappropriate choice is to give the user an index page, and let them
52ea316008e2581c8113441c9c341e5c65225f6anilgunselect. However it is often possible for the server to choose
52ea316008e2581c8113441c9c341e5c65225f6anilgunautomatically. This works because browsers can send as part of each
52ea316008e2581c8113441c9c341e5c65225f6anilgunrequest information about what representations they prefer. For
52ea316008e2581c8113441c9c341e5c65225f6anilgunexample, a browser could indicate that it would like to see
52ea316008e2581c8113441c9c341e5c65225f6anilguninformation in French, if possible, else English will do. Browsers
52ea316008e2581c8113441c9c341e5c65225f6anilgunindicate their preferences by headers in the request. To request only
52ea316008e2581c8113441c9c341e5c65225f6anilgunFrench representations, the browser would send
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgun<pre>
52ea316008e2581c8113441c9c341e5c65225f6anilgun Accept-Language: fr
52ea316008e2581c8113441c9c341e5c65225f6anilgun</pre>
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgunNote that this preference will only be applied when there is a choice
52ea316008e2581c8113441c9c341e5c65225f6anilgunof representations and they vary by language.
52ea316008e2581c8113441c9c341e5c65225f6anilgun<p>
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgunAs an example of a more complex request, this browser has been
52ea316008e2581c8113441c9c341e5c65225f6anilgunconfigured to accept French and English, but prefer French, and to
52ea316008e2581c8113441c9c341e5c65225f6anilgunaccept various media types, preferring HTML over plain text or other
52ea316008e2581c8113441c9c341e5c65225f6anilguntext types, and preferring GIF or JPEG over other media types, but also
52ea316008e2581c8113441c9c341e5c65225f6anilgunallowing any other media type as a last resort:
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh
52ea316008e2581c8113441c9c341e5c65225f6anilgun<pre>
52ea316008e2581c8113441c9c341e5c65225f6anilgun Accept-Language: fr; q=1.0, en; q=0.5
52ea316008e2581c8113441c9c341e5c65225f6anilgun Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6,
52ea316008e2581c8113441c9c341e5c65225f6anilgun image/jpeg; q=0.6, image/*; q=0.5, */*; q=0.1
52ea316008e2581c8113441c9c341e5c65225f6anilgun</pre>
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgunApache 1.2 supports 'server driven' content negotiation, as defined in
52ea316008e2581c8113441c9c341e5c65225f6anilgunthe HTTP/1.1 specification. It fully supports the Accept,
52ea316008e2581c8113441c9c341e5c65225f6anilgunAccept-Language, Accept-Charset and Accept-Encoding request headers.
52ea316008e2581c8113441c9c341e5c65225f6anilgun<p>
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgunThe terms used in content negotiation are: a <b>resource</b> is an
52ea316008e2581c8113441c9c341e5c65225f6anilgunitem which can be requested of a server, which might be selected as
52ea316008e2581c8113441c9c341e5c65225f6anilgunthe result of a content negotiation algorithm. If a resource is
52ea316008e2581c8113441c9c341e5c65225f6anilgunavailable in several formats, these are called <b>representations</b>
52ea316008e2581c8113441c9c341e5c65225f6anilgunor <b>variants</b>. The ways in which the variants for a particular
52ea316008e2581c8113441c9c341e5c65225f6anilgunresource vary are called the <b>dimensions</b> of negotiation.
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgun<h2>Negotiation in Apache</h2>
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgunIn order to negotiate a resource, the server needs to be given
52ea316008e2581c8113441c9c341e5c65225f6anilguninformation about each of the variants. This is done in one of two
52ea316008e2581c8113441c9c341e5c65225f6anilgunways:
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgun<ul>
52ea316008e2581c8113441c9c341e5c65225f6anilgun <li> Using a type map (i.e., a <code>*.var</code> file) which
52ea316008e2581c8113441c9c341e5c65225f6anilgun names the files containing the variants explicitly
52ea316008e2581c8113441c9c341e5c65225f6anilgun <li> Or using a 'MultiViews' search, where the server does an implicit
52ea316008e2581c8113441c9c341e5c65225f6anilgun filename pattern match, and chooses from among the results.
52ea316008e2581c8113441c9c341e5c65225f6anilgun</ul>
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgun<h3>Using a type-map file</h3>
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgunA type map is a document which is associated with the handler
52ea316008e2581c8113441c9c341e5c65225f6anilgunnamed <code>type-map</code> (or, for backwards-compatibility with
52ea316008e2581c8113441c9c341e5c65225f6anilgunolder Apache configurations, the mime type
52ea316008e2581c8113441c9c341e5c65225f6anilgun<code>application/x-type-map</code>). Note that to use this feature,
52ea316008e2581c8113441c9c341e5c65225f6anilgunyou've got to have a <code>SetHandler</code> some place which defines a
52ea316008e2581c8113441c9c341e5c65225f6anilgunfile suffix as <code>type-map</code>; this is best done with a
52ea316008e2581c8113441c9c341e5c65225f6anilgun<pre>
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgun AddHandler type-map var
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgun</pre>
52ea316008e2581c8113441c9c341e5c65225f6anilgunin <code>srm.conf</code>. See comments in the sample config files for
52ea316008e2581c8113441c9c341e5c65225f6anilgundetails. <p>
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgunType map files have an entry for each available variant; these entries
52ea316008e2581c8113441c9c341e5c65225f6anilgunconsist of contiguous RFC822-format header lines. Entries for
52ea316008e2581c8113441c9c341e5c65225f6anilgundifferent variants are separated by blank lines. Blank lines are
52ea316008e2581c8113441c9c341e5c65225f6anilgunillegal within an entry. It is conventional to begin a map file with
52ea316008e2581c8113441c9c341e5c65225f6anilgunan entry for the combined entity as a whole (although this
52ea316008e2581c8113441c9c341e5c65225f6anilgunis not required, and if present will be ignored). An example
52ea316008e2581c8113441c9c341e5c65225f6anilgunmap file is:
52ea316008e2581c8113441c9c341e5c65225f6anilgun<pre>
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgun URI: foo
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgun URI: foo.en.html
52ea316008e2581c8113441c9c341e5c65225f6anilgun Content-type: text/html
52ea316008e2581c8113441c9c341e5c65225f6anilgun Content-language: en
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgun URI: foo.fr.de.html
52ea316008e2581c8113441c9c341e5c65225f6anilgun Content-type: text/html; charset=iso-8859-2
52ea316008e2581c8113441c9c341e5c65225f6anilgun Content-language: fr, de
52ea316008e2581c8113441c9c341e5c65225f6anilgun</pre>
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgunIf the variants have different source qualities, that may be indicated
52ea316008e2581c8113441c9c341e5c65225f6anilgunby the "qs" parameter to the media type, as in this picture (available
52ea316008e2581c8113441c9c341e5c65225f6anilgunas jpeg, gif, or ASCII-art):
52ea316008e2581c8113441c9c341e5c65225f6anilgun<pre>
52ea316008e2581c8113441c9c341e5c65225f6anilgun URI: foo
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgun URI: foo.jpeg
52ea316008e2581c8113441c9c341e5c65225f6anilgun Content-type: image/jpeg; qs=0.8
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgun URI: foo.gif
52ea316008e2581c8113441c9c341e5c65225f6anilgun Content-type: image/gif; qs=0.5
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgun URI: foo.txt
52ea316008e2581c8113441c9c341e5c65225f6anilgun Content-type: text/plain; qs=0.01
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgun</pre>
52ea316008e2581c8113441c9c341e5c65225f6anilgun<p>
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgunqs values can vary between 0.000 and 1.000. Note that any variant with
52ea316008e2581c8113441c9c341e5c65225f6anilguna qs value of 0.000 will never be chosen. Variants with no 'qs'
52ea316008e2581c8113441c9c341e5c65225f6anilgunparameter value are given a qs factor of 1.0. <p>
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgunThe full list of headers recognized is:
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgun<dl>
52ea316008e2581c8113441c9c341e5c65225f6anilgun <dt> <code>URI:</code>
52ea316008e2581c8113441c9c341e5c65225f6anilgun <dd> uri of the file containing the variant (of the given media
52ea316008e2581c8113441c9c341e5c65225f6anilgun type, encoded with the given content encoding). These are
52ea316008e2581c8113441c9c341e5c65225f6anilgun interpreted as URLs relative to the map file; they must be on
52ea316008e2581c8113441c9c341e5c65225f6anilgun the same server (!), and they must refer to files to which the
52ea316008e2581c8113441c9c341e5c65225f6anilgun client would be granted access if they were to be requested
52ea316008e2581c8113441c9c341e5c65225f6anilgun directly.
52ea316008e2581c8113441c9c341e5c65225f6anilgun <dt> <code>Content-type:</code>
52ea316008e2581c8113441c9c341e5c65225f6anilgun <dd> media type --- charset, level and "qs" parameters may be given. These
52ea316008e2581c8113441c9c341e5c65225f6anilgun are often referred to as MIME types; typical media types are
52ea316008e2581c8113441c9c341e5c65225f6anilgun <code>image/gif</code>, <code>text/plain</code>, or
52ea316008e2581c8113441c9c341e5c65225f6anilgun <code>text/html;&nbsp;level=3</code>.
52ea316008e2581c8113441c9c341e5c65225f6anilgun <dt> <code>Content-language:</code>
52ea316008e2581c8113441c9c341e5c65225f6anilgun <dd> The languages of the variant, specified as an Internet standard
52ea316008e2581c8113441c9c341e5c65225f6anilgun language code (e.g., <code>en</code> for English,
52ea316008e2581c8113441c9c341e5c65225f6anilgun <code>kr</code> for Korean, etc.).
52ea316008e2581c8113441c9c341e5c65225f6anilgun <dt> <code>Content-encoding:</code>
52ea316008e2581c8113441c9c341e5c65225f6anilgun <dd> If the file is compressed, or otherwise encoded, rather than
52ea316008e2581c8113441c9c341e5c65225f6anilgun containing the actual raw data, this says how that was done.
52ea316008e2581c8113441c9c341e5c65225f6anilgun For compressed files (the only case where this generally comes
52ea316008e2581c8113441c9c341e5c65225f6anilgun up), content encoding should be
52ea316008e2581c8113441c9c341e5c65225f6anilgun <code>x-compress</code>, or <code>x-gzip</code>, as appropriate.
52ea316008e2581c8113441c9c341e5c65225f6anilgun <dt> <code>Content-length:</code>
52ea316008e2581c8113441c9c341e5c65225f6anilgun <dd> The size of the file. Clients can ask to receive a given media
52ea316008e2581c8113441c9c341e5c65225f6anilgun type only if the variant isn't too big; specifying a content
52ea316008e2581c8113441c9c341e5c65225f6anilgun length in the map allows the server to compare against these
52ea316008e2581c8113441c9c341e5c65225f6anilgun thresholds without checking the actual file.
52ea316008e2581c8113441c9c341e5c65225f6anilgun</dl>
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgun<h3>Multiviews</h3>
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgunThis is a per-directory option, meaning it can be set with an
52ea316008e2581c8113441c9c341e5c65225f6anilgun<code>Options</code> directive within a <code>&lt;Directory&gt;</code>,
52ea316008e2581c8113441c9c341e5c65225f6anilgun<code>&lt;Location&gt;</code> or <code>&lt;Files&gt;</code>
52ea316008e2581c8113441c9c341e5c65225f6anilgunsection in <code>access.conf</code>, or (if <code>AllowOverride</code>
52ea316008e2581c8113441c9c341e5c65225f6anilgunis properly set) in <code>.htaccess</code> files. Note that
52ea316008e2581c8113441c9c341e5c65225f6anilgun<code>Options All</code> does not set <code>MultiViews</code>; you
52ea316008e2581c8113441c9c341e5c65225f6anilgunhave to ask for it by name. (Fixing this is a one-line change to
52ea316008e2581c8113441c9c341e5c65225f6anilgun<code>http_core.h</code>).
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgun<p>
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgunThe effect of <code>MultiViews</code> is as follows: if the server
52ea316008e2581c8113441c9c341e5c65225f6anilgunreceives a request for <code>/some/dir/foo</code>, if
52ea316008e2581c8113441c9c341e5c65225f6anilgun<code>/some/dir</code> has <code>MultiViews</code> enabled, and
52ea316008e2581c8113441c9c341e5c65225f6anilgun<code>/some/dir/foo</code> does <em>not</em> exist, then the server reads the
52ea316008e2581c8113441c9c341e5c65225f6anilgundirectory looking for files named foo.*, and effectively fakes up a
52ea316008e2581c8113441c9c341e5c65225f6anilguntype map which names all those files, assigning them the same media
52ea316008e2581c8113441c9c341e5c65225f6anilguntypes and content-encodings it would have if the client had asked for
52ea316008e2581c8113441c9c341e5c65225f6anilgunone of them by name. It then chooses the best match to the client's
52ea316008e2581c8113441c9c341e5c65225f6anilgunrequirements, and forwards them along.
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgun<p>
52ea316008e2581c8113441c9c341e5c65225f6anilgun
52ea316008e2581c8113441c9c341e5c65225f6anilgunThis applies to searches for the file named by the
52ea316008e2581c8113441c9c341e5c65225f6anilgun<code>DirectoryIndex</code> directive, if the server is trying to
52ea316008e2581c8113441c9c341e5c65225f6anilgunindex a directory; if the configuration files specify
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung<pre>
727872d18412fc021f03969b8641810d8896820bhumbedooh
0d0ba3a410038e179b695446bb149cce6264e0abnd DirectoryIndex index
727872d18412fc021f03969b8641810d8896820bhumbedooh
cc7e1025de9ac63bd4db6fe7f71c158b2cf09fe4humbedooh</pre> then the server will arbitrate between <code>index.html</code>
0d0ba3a410038e179b695446bb149cce6264e0abndand <code>index.html3</code> if both are present. If neither are
cc7e1025de9ac63bd4db6fe7f71c158b2cf09fe4humbedoohpresent, and <code>index.cgi</code> is there, the server will run it.
727872d18412fc021f03969b8641810d8896820bhumbedooh
0d0ba3a410038e179b695446bb149cce6264e0abnd<p>
0d0ba3a410038e179b695446bb149cce6264e0abnd
0d0ba3a410038e179b695446bb149cce6264e0abndIf one of the files found when reading the directive is a CGI script,
ac082aefa89416cbdc9a1836eaf3bed9698201c8humbedoohit's not obvious what should happen. The code gives that case
0d0ba3a410038e179b695446bb149cce6264e0abndspecial treatment --- if the request was a POST, or a GET with
0d0ba3a410038e179b695446bb149cce6264e0abndQUERY_ARGS or PATH_INFO, the script is given an extremely high quality
0d0ba3a410038e179b695446bb149cce6264e0abndrating, and generally invoked; otherwise it is given an extremely low
727872d18412fc021f03969b8641810d8896820bhumbedoohquality rating, which generally causes one of the other views (if any)
0d0ba3a410038e179b695446bb149cce6264e0abndto be retrieved.
0d0ba3a410038e179b695446bb149cce6264e0abnd
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh<h2>The Negotiation Algorithm</h2>
5effc8b39fae5cd169d17f342bfc265705840014rbowen
d229f940abfb2490dee17979e9a5ff31b7012eb5rbowenAfter Apache has obtained a list of the variants for a given resource,
0d0ba3a410038e179b695446bb149cce6264e0abndeither from a type-map file or from the filenames in the directory, it
7fec19672a491661b2fe4b29f685bc7f4efa64d4ndapplies a algorithm to decide on the 'best' variant to return, if
7fec19672a491661b2fe4b29f685bc7f4efa64d4ndany. To do this it calculates a quality value for each variant in each
7fec19672a491661b2fe4b29f685bc7f4efa64d4ndof the dimensions of variance. It is not necessary to know any of the
52ea316008e2581c8113441c9c341e5c65225f6anilgundetails of how negotiation actually takes place in order to use Apache's
content negotiation features. However the rest of this document
explains in detail the algorithm used for those interested. <p>
In some circumstances, Apache can 'fiddle' the quality factor of a
particular dimension to achieve a better result. The ways Apache can
fiddle quality factors is explained in more detail below.
<h3>Dimensions of Negotiation</h3>
<table>
<tr><th>Dimension
<th>Notes
<tr><td>Media Type
<td>Browser indicates preferences on Accept: header. Each item
can have an associated quality factor. Variant description can also
have a quality factor.
<tr><td>Language
<td>Browser indicates preferences on Accept-Language: header. Each
item
can have a quality factor. Variants can be associated with none, one
or more languages.
<tr><td>Encoding
<td>Browser indicates preference with Accept-Encoding: header.
<tr><td>Charset
<td>Browser indicates preference with Accept-Charset: header. Variants
can indicate a charset as a parameter of the media type.
</table>
<h3>Apache Negotiation Algorithm</h3>
Apache uses an algorithm to select the 'best' variant (if any) to
return to the browser. This algorithm is not configurable. It operates
like this:
<p>
<ol>
<li>
Firstly, for each dimension of the negotiation, the appropriate
Accept header is checked and a quality assigned to this each
variant. If the Accept header for any dimension means that this
variant is not acceptable, eliminate it. If no variants remain, go
to step 4.
<li>Select the 'best' variant by a process of elimination. Each of
the following tests is applied in order. Any variants not selected at
each stage are eliminated. After each test, if only one variant
remains, it is selected as the best match. If more than one variant
remains, move onto the next test.
<ol>
<li>Multiply the quality factor from the Accept header with the
quality-of-source factor for this variant's media type, and select
the variants with the highest value
<li>Select the variants with the highest language quality factor
<li>Select the variants with the best language match, using either the
order of languages on the <code>LanguagePriority</code> directive (if present),
else the order of languages on the Accept-Language header.
<li>Select the variants with the highest 'level' media parameter
(used to give the version of text/html media types).
<li>Select only unencoded variants, if there is a mix of encoded
and non-encoded variants. If either all variants are encoded
or all variants are not encoded, select all.
<li>Select only variants with acceptable charset media parameters,
as given on the Accept-Charset header line. Charset ISO-8859-1
is always acceptable. Variants not associated with a particular
charset are assumed to be in ISO-8859-1.
<li>Select the variants with the smallest content length
<li>Select the first variant of those remaining (this will be either the
first listed in the type-map file, or the first read from the directory)
and go to stage 3.
</ol>
<li>The algorithm has now selected one 'best' variant, so return
it as the response. The HTTP response header Vary is set to indicate the
dimensions of negotiation (browsers and caches can use this
information when caching the resource). End.
<li>To get here means no variant was selected (because non are acceptable
to the browser). Return a 406 status (meaning "No acceptable representation")
with a response body consisting of an HTML document listing the
available variants. Also set the HTTP Vary header to indicate the
dimensions of variance.
</ol>
<h2><a name="better">Fiddling with Quality Values</a></h2>
Apache sometimes changes the quality values from what would be
expected by a strict interpretation of the algorithm above. This is to
get a better result from the algorithm for browsers which do not send
full or accurate information. Some of the most popular browsers send
Accept header information which would otherwise result in the
selection of the wrong variant in many cases. If a browser
sends full and correct information these fiddles will not
be applied.
<p>
<h3>Media Types and Wildcards</h3>
The Accept: request header indicates preferences for media types. It
can also include 'wildcard' media types, such as "image/*" or "*/*"
where the * matches any string. So a request including:
<pre>
Accept: image/*, */*
</pre>
would indicate that any type starting "image/" is acceptable,
as is any other type (so the first "image/*" is redundant). Some
browsers routinely send wildcards in addition to explicit types they
can handle. For example:
<pre>
Accept: text/html, text/plain, image/gif, image/jpeg, */*
</pre>
The intention of this is to indicate that the explicitly
listed types are preferred, but if a different representation is
available, that is ok too. However under the basic algorithm, as given
above, the */* wildcard has exactly equal preference to all the other
types, so they are not being preferred. The browser should really have
sent a request with a lower quality (preference) value for *.*, such
as:
<pre>
Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01
</pre>
The explicit types have no quality factor, so they default to a
preference of 1.0 (the highest). The wildcard */* is given
a low preference of 0.01, so other types will only be returned if
no variant matches an explicitly listed type.
<p>
If the Accept: header contains <i>no</i> q factors at all, Apache sets
the q value of "*/*", if present, to 0.01 to emulate the desired
behavior. It also sets the q value of wildcards of the format
"type/*" to 0.02 (so these are preferred over matches against
"*/*". If any media type on the Accept: header contains a q factor,
these special values are <i>not</i> applied, so requests from browsers
which send the correct information to start with work as expected.
<h3>Variants with no Language</h3>
If some of the variants for a particular resource have a language
attribute, and some do not, those variants with no language
are given a very low language quality factor of 0.001.<p>
The reason for setting this language quality factor for
variant with no language to a very low value is to allow
for a default variant which can be supplied if none of the
other variants match the browser's language preferences.
For example, consider the situation with three variants:
<ul>
<li>foo.en.html, language en
<li>foo.fr.html, language en
<li>foo.html, no language
</ul>
The meaning of a variant with no language is that it is
always acceptable to the browser. If the request Accept-Language
header includes either en or fr (or both) one of foo.en.html
or foo.fr.html will be returned. If the browser does not list
either en or fr as acceptable, foo.html will be returned instead.
<h2>Note on Caching</h2>
When a cache stores a document, it associates it with the request URL.
The next time that URL is requested, the cache can use the stored
document, provided it is still within date. But if the resource is
subject to content negotiation at the server, this would result in
only the first requested variant being cached, and subsequent cache
hits could return the wrong response. To prevent this,
Apache normally marks all responses that are returned after content negotiation
as non-cacheable by HTTP/1.0 clients. Apache also supports the HTTP/1.1
protocol features to allow caching of negotiated responses. <P>
For requests which come from a HTTP/1.0 compliant client (either a
browser or a cache), the directive <tt>CacheNegotiatedDocs</tt> can be
used to allow caching of responses which were subject to negotiation.
This directive can be given in the server config or virtual host, and
takes no arguments. It has no effect on requests from HTTP/1.1
clients.
<!--#include virtual="footer.html" -->
</BODY>
</HTML>