content-negotiation.html revision b898ccd2b9aad43056f06f89badc75b3b60ebb40
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes BGCOLOR="#FFFFFF"
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes TEXT="#000000"
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes LINK="#0000FF"
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes VLINK="#000080"
0662ed52e814f8f08ef0e09956413a792584eddffuankg ALINK="#FF0000"
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<!--#include virtual="header.html" -->
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesApache's support for content negotiation has been updated to meet the
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesHTTP/1.1 specification. It can choose the best representation of a
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesresource based on the browser-supplied preferences for media type,
bb2b38cd44b032118359afbc743efbea12f48e61bnicholeslanguages, character set and encoding. It is also implements a
bb2b38cd44b032118359afbc743efbea12f48e61bnicholescouple of features to give more intelligent handling of requests from
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesbrowsers which send incomplete negotiation information. <P>
70953fb44a7140fe206c3a5f011e24209c8c5c6abnicholesContent negotiation is provided by the
70953fb44a7140fe206c3a5f011e24209c8c5c6abnicholes<A HREF="mod/mod_negotiation.html">mod_negotiation</A> module,
bb2b38cd44b032118359afbc743efbea12f48e61bnicholeswhich is compiled in by default.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesA resource may be available in several different representations. For
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesexample, it might be available in different languages or different
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesmedia types, or a combination. One way of selecting the most
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesappropriate choice is to give the user an index page, and let them
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesselect. However it is often possible for the server to choose
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesautomatically. This works because browsers can send as part of each
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesrequest information about what representations they prefer. For
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesexample, a browser could indicate that it would like to see
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesinformation in French, if possible, else English will do. Browsers
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesindicate their preferences by headers in the request. To request only
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesFrench representations, the browser would send
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes Accept-Language: fr
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesNote that this preference will only be applied when there is a choice
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesof representations and they vary by language.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesAs an example of a more complex request, this browser has been
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesconfigured to accept French and English, but prefer French, and to
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesaccept various media types, preferring HTML over plain text or other
bb2b38cd44b032118359afbc743efbea12f48e61bnicholestext types, and preferring GIF or JPEG over other media types, but also
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesallowing any other media type as a last resort:
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes Accept-Language: fr; q=1.0, en; q=0.5
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6,
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesApache 1.2 supports 'server driven' content negotiation, as defined in
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesthe HTTP/1.1 specification. It fully supports the Accept,
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesAccept-Language, Accept-Charset and Accept-Encoding request headers.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesApache 1.3.4 also supports 'transparent' content negotiation, which is
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesan experimental negotiation protocol defined in RFC 2295 and RFC 2296.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesIt does not offer support for 'feature negotiation' as defined in
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesA <STRONG>resource</STRONG> is a conceptual entity identified by a URI
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes(RFC 2396). An HTTP server like Apache provides access to
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<STRONG>representations</STRONG> of the resource(s) within its namespace,
ac7985784d08a3655291f24f711812b4d8b1cbcffuankgwith each representation in the form of a sequence of bytes with a
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesdefined media type, character set, encoding, etc. Each resource may be
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesassociated with zero, one, or more than one representation
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesat any given time. If multiple representations are available,
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesthe resource is referred to as <STRONG>negotiable</STRONG> and each of its
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesrepresentations is termed a <STRONG>variant</STRONG>. The ways in which the
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesvariants for a negotiable resource vary are called the
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesIn order to negotiate a resource, the server needs to be given
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesinformation about each of the variants. This is done in one of two
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes <LI> Using a type map (<EM>i.e.</EM>, a <CODE>*.var</CODE> file) which
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes names the files containing the variants explicitly, or
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes <LI> Using a 'MultiViews' search, where the server does an implicit
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes filename pattern match and chooses from among the results.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesA type map is a document which is associated with the handler
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesnamed <CODE>type-map</CODE> (or, for backwards-compatibility with
0a39e7683f6611d66c55712f50bb240428d832a1bnicholesolder Apache configurations, the mime type
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<CODE>application/x-type-map</CODE>). Note that to use this feature,
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesyou must have a handler set in the configuration that defines a
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesfile suffix as <CODE>type-map</CODE>; this is best done with a
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes AddHandler type-map .var
ac7985784d08a3655291f24f711812b4d8b1cbcffuankgin the server configuration file. See the comments in the sample config
0662ed52e814f8f08ef0e09956413a792584eddffuankgfile for more details. <P>
ac7985784d08a3655291f24f711812b4d8b1cbcffuankgType map files have an entry for each available variant; these entries
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesconsist of contiguous HTTP-format header lines. Entries for
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesdifferent variants are separated by blank lines. Blank lines are
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesillegal within an entry. It is conventional to begin a map file with
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesan entry for the combined entity as a whole (although this
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesis not required, and if present will be ignored). An example
ac7985784d08a3655291f24f711812b4d8b1cbcffuankgmap file is:
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes Content-language: en
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes Content-language: fr, de
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesIf the variants have different source qualities, that may be indicated
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesby the "qs" parameter to the media type, as in this picture (available
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesas jpeg, gif, or ASCII-art):
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesqs values can vary in the range 0.000 to 1.000. Note that any variant with
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesa qs value of 0.000 will never be chosen. Variants with no 'qs'
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesparameter value are given a qs factor of 1.0. The qs parameter indicates
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesthe relative 'quality' of this variant compared to the other available
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesvariants, independent of the client's capabilities. For example, a jpeg
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesfile is usually of higher source quality than an ascii file if it is
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesattempting to represent a photograph. However, if the resource being
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesrepresented is an original ascii art, then an ascii representation would
bb2b38cd44b032118359afbc743efbea12f48e61bnicholeshave a higher source quality than a jpeg representation. A qs value
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesis therefore specific to a given variant depending on the nature of
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesthe resource it represents.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesThe full list of headers recognized is:
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes <DD> uri of the file containing the variant (of the given media
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes type, encoded with the given content encoding). These are
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes interpreted as URLs relative to the map file; they must be on
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes the same server (!), and they must refer to files to which the
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes client would be granted access if they were to be requested
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes <DD> media type --- charset, level and "qs" parameters may be given. These
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes are often referred to as MIME types; typical media types are
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes <CODE>image/gif</CODE>, <CODE>text/plain</CODE>, or
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes <DD> The languages of the variant, specified as an Internet standard
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes language tag from RFC 1766 (<EM>e.g.</EM>, <CODE>en</CODE> for English,
cf7ca2f9eaa6523fefcccba4287b91637391fb51fuankg <DD> If the file is compressed, or otherwise encoded, rather than
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes containing the actual raw data, this says how that was done.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes Apache only recognizes encodings that are defined by an
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes <A HREF="mod/mod_mime.html#addencoding">AddEncoding</A> directive.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes This normally includes the encodings <CODE>x-compress</CODE>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes for compress'd files, and <CODE>x-gzip</CODE> for gzip'd files.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes The <CODE>x-</CODE> prefix is ignored for encoding comparisons.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes <DD> The size of the file. Specifying content
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes lengths in the type-map allows the server to compare file sizes
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes without checking the actual files.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes <DD> A human-readable textual description of the variant. If Apache cannot
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes find any appropriate variant to return, it will return an error
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes response which lists all available variants instead. Such a variant
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes list will include the human-readable variant descriptions.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<CODE>MultiViews</CODE> is a per-directory option, meaning it can be set with
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesan <CODE>Options</CODE> directive within a <CODE><Directory></CODE>,
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<CODE><Location></CODE> or <CODE><Files></CODE>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholessection in <CODE>access.conf</CODE>, or (if <CODE>AllowOverride</CODE>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesis properly set) in <CODE>.htaccess</CODE> files. Note that
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<CODE>Options All</CODE> does not set <CODE>MultiViews</CODE>; you
bb2b38cd44b032118359afbc743efbea12f48e61bnicholeshave to ask for it by name.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesThe effect of <CODE>MultiViews</CODE> is as follows: if the server
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesreceives a request for <CODE>/some/dir/foo</CODE>, if
8ffac2c334103c0336602aaede650cb578611151fuankg<CODE>/some/dir</CODE> has <CODE>MultiViews</CODE> enabled, and
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<CODE>/some/dir/foo</CODE> does <EM>not</EM> exist, then the server reads the
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesdirectory looking for files named foo.*, and effectively fakes up a
ac7985784d08a3655291f24f711812b4d8b1cbcffuankgtype map which names all those files, assigning them the same media
ac7985784d08a3655291f24f711812b4d8b1cbcffuankgtypes and content-encodings it would have if the client had asked for
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesone of them by name. It then chooses the best match to the client's
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesrequirements.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<CODE>MultiViews</CODE> may also apply to searches for the file named by the
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<CODE>DirectoryIndex</CODE> directive, if the server is trying to
ac7985784d08a3655291f24f711812b4d8b1cbcffuankgindex a directory. If the configuration files specify
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes DirectoryIndex index
ac7985784d08a3655291f24f711812b4d8b1cbcffuankgthen the server will arbitrate between <CODE>index.html</CODE>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesand <CODE>index.html3</CODE> if both are present. If neither are
bb2b38cd44b032118359afbc743efbea12f48e61bnicholespresent, and <CODE>index.cgi</CODE> is there, the server will run it.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesIf one of the files found when reading the directive is a CGI script,
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesit's not obvious what should happen. The code gives that case
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesspecial treatment --- if the request was a POST, or a GET with
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesQUERY_ARGS or PATH_INFO, the script is given an extremely high quality
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesrating, and generally invoked; otherwise it is given an extremely low
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesquality rating, which generally causes one of the other views (if any)
ac7985784d08a3655291f24f711812b4d8b1cbcffuankgto be retrieved.
2a3d4464b68bcf6173f675479b4ec681a83f4bd9fuankgAfter Apache has obtained a list of the variants for a given resource,
ac7985784d08a3655291f24f711812b4d8b1cbcffuankgeither from a type-map file or from the filenames in the directory, it
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesinvokes one of two methods to decide on the 'best' variant to
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesreturn, if any. It is not necessary to know any of the details of how
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesnegotiation actually takes place in order to use Apache's content
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesnegotiation features. However the rest of this document explains the
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesmethods used for those interested.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesThere are two negotiation methods:
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<LI><STRONG>Server driven negotiation with the Apache
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" -->