content-negotiation.html revision bf3d9f591e5af24fdcaa9029094dc045878d1d1a
52ea316008e2581c8113441c9c341e5c65225f6anilgun<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
52ea316008e2581c8113441c9c341e5c65225f6anilgun<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
52ea316008e2581c8113441c9c341e5c65225f6anilgun BGCOLOR="#FFFFFF"
52ea316008e2581c8113441c9c341e5c65225f6anilgun TEXT="#000000"
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen LINK="#0000FF"
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen VLINK="#000080"
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen ALINK="#FF0000"
52ea316008e2581c8113441c9c341e5c65225f6anilgun<!--#include virtual="header.html" -->
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>
52ea316008e2581c8113441c9c341e5c65225f6anilgunContent negotiation is provided by the
52ea316008e2581c8113441c9c341e5c65225f6anilgun<a href="mod/mod_negotiation.html">mod_negotiation</a> module,
52ea316008e2581c8113441c9c341e5c65225f6anilgunwhich is compiled in by default.
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 Accept-Language: fr
52ea316008e2581c8113441c9c341e5c65225f6anilgunNote that this preference will only be applied when there is a choice
52ea316008e2581c8113441c9c341e5c65225f6anilgunof representations and they vary by language.
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:
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,
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.
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.
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
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.
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 AddHandler type-map var
52ea316008e2581c8113441c9c341e5c65225f6anilgunin <code>srm.conf</code>. See comments in the sample config files for
52ea316008e2581c8113441c9c341e5c65225f6anilgundetails. <p>
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 Content-language: en
52ea316008e2581c8113441c9c341e5c65225f6anilgun Content-language: fr, de
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):
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>
52ea316008e2581c8113441c9c341e5c65225f6anilgunThe full list of headers recognized is:
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 <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 <dd> The languages of the variant, specified as an Internet standard
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 <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.
52ea316008e2581c8113441c9c341e5c65225f6anilgunThis is a per-directory option, meaning it can be set with an
52ea316008e2581c8113441c9c341e5c65225f6anilgun<code>Options</code> directive within a <code><Directory></code>,
52ea316008e2581c8113441c9c341e5c65225f6anilgun<code><Location></code> or <code><Files></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
52ea316008e2581c8113441c9c341e5c65225f6anilgunThe effect of <code>MultiViews</code> is as follows: if the server
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.
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
0d0ba3a410038e179b695446bb149cce6264e0abnd DirectoryIndex index
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.
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.
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
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.
<!--#include virtual="footer.html" -->