Content Negotiation

Available Languages: en | + fr | + ja | + ko | + tr

+ + +

Apache supports content negotiation as described in + the HTTP/1.1 specification. It can choose the best + representation of a resource based on the browser-supplied + preferences for media type, languages, character set and + encoding. It also implements a couple of features to give + more intelligent handling of requests from browsers that send + incomplete negotiation information.

+ +

Content negotiation is provided by the + mod_negotiation module, which is compiled in + by default.

About Content Negotiation
Negotiation in Apache
The Negotiation Methods
Fiddling with Quality + Values
Extensions to Transparent Content +Negotiation
Note on hyperlinks and naming conventions
Note on Caching

About Content Negotiation

+ +

A resource may be available in several different + representations. For example, it might be available in + different languages or different media types, or a combination. + One way of selecting the most appropriate choice is to give the + user an index page, and let them select. However it is often + possible for the server to choose automatically. This works + because browsers can send, as part of each request, information + about what representations they prefer. For example, a browser + could indicate that it would like to see information in French, + if possible, else English will do. Browsers indicate their + preferences by headers in the request. To request only French + representations, the browser would send

+ +

Accept-Language: fr

+ +

Note that this preference will only be applied when there is + a choice of representations and they vary by language.

+ +

As an example of a more complex request, this browser has + been configured to accept French and English, but prefer + French, and to accept various media types, preferring HTML over + plain text or other text types, and preferring GIF or JPEG over + other media types, but also allowing any other media type as a + last resort:

+ +

+ Accept-Language: fr; q=1.0, en; q=0.5 + Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6, image/jpeg; q=0.6, image/*; q=0.5, */*; q=0.1 +

+ +

Apache supports 'server driven' content negotiation, as + defined in the HTTP/1.1 specification. It fully supports the + Accept, Accept-Language, + Accept-Charset andAccept-Encoding + request headers. Apache also supports 'transparent' + content negotiation, which is an experimental negotiation + protocol defined in RFC 2295 and RFC 2296. It does not offer + support for 'feature negotiation' as defined in these RFCs.

+ +

A resource is a conceptual entity + identified by a URI (RFC 2396). An HTTP server like Apache + provides access to representations of the + resource(s) within its namespace, with each representation in + the form of a sequence of bytes with a defined media type, + character set, encoding, etc. Each resource may be associated + with zero, one, or more than one representation at any given + time. If multiple representations are available, the resource + is referred to as negotiable and each of its + representations is termed a variant. The ways + in which the variants for a negotiable resource vary are called + the dimensions of negotiation.

Negotiation in Apache

+ +

In order to negotiate a resource, the server needs to be + given information about each of the variants. This is done in + one of two ways:

+ +

Using a type map (i.e., a *.var + file) which names the files containing the variants + explicitly, or
Using a 'MultiViews' search, where the server does an + implicit filename pattern match and chooses from among the + results.

+ +

Using a type-map file

+ +

A type map is a document which is associated with the + handler named type-map (or, for + backwards-compatibility with older Apache configurations, the + MIME type application/x-type-map). Note that to + use this feature, you must have a handler set in the + configuration that defines a file suffix as + type-map; this is best done with

+ +

AddHandler type-map .var

+ +

in the server configuration file.

+ +

Type map files should have the same name as the resource + which they are describing, and have an entry for each available + variant; these entries consist of contiguous HTTP-format header + lines. Entries for different variants are separated by blank + lines. Blank lines are illegal within an entry. It is + conventional to begin a map file with an entry for the combined + entity as a whole (although this is not required, and if + present will be ignored). An example map file is shown below. + This file would be named foo.var, as it describes + a resource named foo.

+ +

+ URI: foo + + URI: foo.en.html + Content-type: text/html + Content-language: en + + URI: foo.fr.de.html + Content-type: text/html;charset=iso-8859-2 + Content-language: fr, de +

Note also that a typemap file will take precedence over the + filename's extension, even when Multiviews is on. If the + variants have different source qualities, that may be indicated + by the "qs" parameter to the media type, as in this picture + (available as JPEG, GIF, or ASCII-art):

+ +

+ URI: foo + + URI: foo.jpeg + Content-type: image/jpeg; qs=0.8 + + URI: foo.gif + Content-type: image/gif; qs=0.5 + + URI: foo.txt + Content-type: text/plain; qs=0.01 +

+ +

qs values can vary in the range 0.000 to 1.000. Note that + any variant with a qs value of 0.000 will never be chosen. + Variants with no 'qs' parameter value are given a qs factor of + 1.0. The qs parameter indicates the relative 'quality' of this + variant compared to the other available variants, independent + of the client's capabilities. For example, a JPEG file is + usually of higher source quality than an ASCII file if it is + attempting to represent a photograph. However, if the resource + being represented is an original ASCII art, then an ASCII + representation would have a higher source quality than a JPEG + representation. A qs value is therefore specific to a given + variant depending on the nature of the resource it + represents.

+ +

The full list of headers recognized is available in the mod_negotation + typemap documentation.

+ + +

Multiviews

+ +

MultiViews is a per-directory option, meaning it + can be set with an Options + directive within a <Directory>, <Location> or <Files> section in + httpd.conf, or (if AllowOverride is properly set) in + .htaccess files. Note that Options All + does not set MultiViews; you have to ask for it by + name.

+ +

The effect of MultiViews is as follows: if the + server receives a request for /some/dir/foo, if + /some/dir has MultiViews enabled, and + /some/dir/foo does not exist, then the + server reads the directory looking for files named foo.*, and + effectively fakes up a type map which names all those files, + assigning them the same media types and content-encodings it + would have if the client had asked for one of them by name. It + then chooses the best match to the client's requirements.

+ +

MultiViews may also apply to searches for the file + named by the DirectoryIndex directive, if the + server is trying to index a directory. If the configuration files + specify

DirectoryIndex index

then the server will arbitrate between index.html + and index.html3 if both are present. If neither + are present, and index.cgi is there, the server + will run it.

+ +

If one of the files found when reading the directory does not + have an extension recognized by mod_mime to designate + its Charset, Content-Type, Language, or Encoding, then the result + depends on the setting of the MultiViewsMatch directive. This + directive determines whether handlers, filters, and other + extension types can participate in MultiViews negotiation.

+ +

The Negotiation Methods

+ +

After Apache has obtained a list of the variants for a given + resource, either from a type-map file or from the filenames in + the directory, it invokes one of two methods to decide on the + 'best' variant to return, if any. It is not necessary to know + any of the details of how negotiation actually takes place in + order to use Apache's content negotiation features. However the + rest of this document explains the methods used for those + interested.

+ +

There are two negotiation methods:

+ +

Server driven negotiation with the Apache + algorithm is used in the normal case. The Apache + algorithm is explained in more detail below. When this + algorithm is used, Apache can sometimes '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.
Transparent content negotiation is used + when the browser specifically requests this through the + mechanism defined in RFC 2295. This negotiation method gives + the browser full control over deciding on the 'best' variant, + the result is therefore dependent on the specific algorithms + used by the browser. As part of the transparent negotiation + process, the browser can ask Apache to run the 'remote + variant selection algorithm' defined in RFC 2296.

+ +

Dimensions of Negotiation

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Dimension	Notes
Media Type	Browser indicates preferences with the `Accept` + header field. Each item can have an associated quality factor. + Variant description can also have a quality factor (the "qs" + parameter).
Language	Browser indicates preferences with the + `Accept-Language` header field. Each item can have + a quality factor. Variants can be associated with none, one or + more than one language.
Encoding	Browser indicates preference with the + `Accept-Encoding` header field. Each item can have + a quality factor.
Charset	Browser indicates preference with the + `Accept-Charset` header field. Each item can have a + quality factor. Variants can indicate a charset as a parameter + of the media type.

+ + +

Apache Negotiation Algorithm

+ +

Apache can use the following algorithm to select the 'best' + variant (if any) to return to the browser. This algorithm is + not further configurable. It operates as follows:

+ +

First, for each dimension of the negotiation, check the + appropriate Accept* header field and assign a + quality to each variant. If the Accept* header for + any dimension implies that this variant is not acceptable, + eliminate it. If no variants remain, go to step 4.
+ Select the 'best' variant by a process of elimination. Each + of the following tests is applied in order. Any variants + not selected at each test are eliminated. After each test, + if only one variant remains, select it as the best match + and proceed to step 3. If more than one variant remains, + move on to the next test. + +
1. Multiply the quality factor from the Accept + header with the quality-of-source factor for this variants + media type, and select the variants with the highest + value.
2. Select the variants with the highest language quality + factor.
3. Select the variants with the best language match, + using either the order of languages in the + Accept-Language header (if present), or else + the order of languages in the LanguagePriority + directive (if present).
4. Select the variants with the highest 'level' media + parameter (used to give the version of text/html media + types).
5. Select variants with the best charset media + parameters, as given on the Accept-Charset + header line. Charset ISO-8859-1 is acceptable unless + explicitly excluded. Variants with a text/* + media type but not explicitly associated with a particular + charset are assumed to be in ISO-8859-1.
6. Select those variants which have associated charset + media parameters that are not ISO-8859-1. If + there are no such variants, select all variants + instead.
7. Select the variants with the best encoding. If there + are variants with an encoding that is acceptable to the + user-agent, select only these variants. Otherwise if + there is a mix of encoded and non-encoded variants, + select only the unencoded variants. If either all + variants are encoded or all variants are not encoded, + select all variants.
8. Select the variants with the smallest content + length.
9. Select the first variant of those remaining. This + will be either the first listed in the type-map file, or + when variants are read from the directory, the one whose + file name comes first when sorted using ASCII code + order.
+
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.
To get here means no variant was selected (because none + 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.

+ +

Fiddling with Quality + Values

+ +

Apache sometimes changes the quality values from what would + be expected by a strict interpretation of the Apache + negotiation 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.

+ +

Media Types and Wildcards

+ +

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:

+ +

Accept: image/*, */*

+ +

would indicate that any type starting "image/" is acceptable, + as is any other type. + Some browsers routinely send wildcards in addition to explicit + types they can handle. For example:

+ +

+ Accept: text/html, text/plain, image/gif, image/jpeg, */* +

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. Using explicit quality values, + what the browser really wants is something like:

+ Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01 +

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.

+ +

If the Accept: header contains no 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 not applied, so requests from browsers which + send the explicit information to start with work as expected.

+ + +

Language Negotiation Exceptions

+ +

New in Apache 2.0, some exceptions have been added to the + negotiation algorithm to allow graceful fallback when language + negotiation fails to find a match.

+ +

When a client requests a page on your server, but the server + cannot find a single page that matches the + Accept-language sent by + the browser, the server will return either a "No Acceptable + Variant" or "Multiple Choices" response to the client. To avoid + these error messages, it is possible to configure Apache to ignore + the Accept-language in these cases and provide a + document that does not explicitly match the client's request. The + ForceLanguagePriority + directive can be used to override one or both of these error + messages and substitute the servers judgement in the form of the + LanguagePriority + directive.

+ +

The server will also attempt to match language-subsets when no + other match can be found. For example, if a client requests + documents with the language en-GB for British + English, the server is not normally allowed by the HTTP/1.1 + standard to match that against a document that is marked as simply + en. (Note that it is almost surely a configuration + error to include en-GB and not en in the + Accept-Language header, since it is very unlikely + that a reader understands British English, but doesn't understand + English in general. Unfortunately, many current clients have + default configurations that resemble this.) However, if no other + language match is possible and the server is about to return a "No + Acceptable Variants" error or fallback to the LanguagePriority, the server + will ignore the subset specification and match en-GB + against en documents. Implicitly, Apache will add + the parent language to the client's acceptable language list with + a very low quality value. But note that if the client requests + "en-GB; q=0.9, fr; q=0.8", and the server has documents + designated "en" and "fr", then the "fr" document will be returned. + This is necessary to maintain compliance with the HTTP/1.1 + specification and to work effectively with properly configured + clients.

+ +

In order to support advanced techniques (such as cookies or + special URL-paths) to determine the user's preferred language, + since Apache 2.0.47 mod_negotiation recognizes + the environment variable + prefer-language. If it exists and contains an + appropriate language tag, mod_negotiation will + try to select a matching variant. If there's no such variant, + the normal negotiation process applies.

+ +

Example

+ SetEnvIf Cookie "language=en" prefer-language=en + SetEnvIf Cookie "language=fr" prefer-language=fr +

+ +

Extensions to Transparent Content +Negotiation

+ +

Apache extends the transparent content negotiation protocol (RFC +2295) as follows. A new {encoding ..} element is used in +variant lists to label variants which are available with a specific +content-encoding only. The implementation of the RVSA/1.0 algorithm +(RFC 2296) is extended to recognize encoded variants in the list, and +to use them as candidate variants whenever their encodings are +acceptable according to the Accept-Encoding request +header. The RVSA/1.0 implementation does not round computed quality +factors to 5 decimal places before choosing the best variant.

Note on hyperlinks and naming conventions

+ +

If you are using language negotiation you can choose between + different naming conventions, because files can have more than + one extension, and the order of the extensions is normally + irrelevant (see the mod_mime documentation + for details).

+ +

A typical file has a MIME-type extension (e.g., + html), maybe an encoding extension (e.g., + gz), and of course a language extension + (e.g., en) when we have different + language variants of this file.

+ +

Examples:

+ +

foo.en.html
foo.html.en
foo.en.html.gz

+ +

Here some more examples of filenames together with valid and + invalid hyperlinks:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Filename	Valid hyperlink	Invalid hyperlink
foo.html.en	foo + foo.html	-
foo.en.html	foo	foo.html
foo.html.en.gz	foo + foo.html	foo.gz + foo.html.gz
foo.en.html.gz	foo	foo.html + foo.html.gz + foo.gz
foo.gz.html.en	foo + foo.gz + foo.gz.html	foo.html
foo.html.gz.en	foo + foo.html + foo.html.gz	foo.gz

+ +

Looking at the table above, you will notice that it is always + possible to use the name without any extensions in a hyperlink + (e.g., foo). The advantage is that you + can hide the actual type of a document rsp. file and can change + it later, e.g., from html to + shtml or cgi without changing any + hyperlink references.

+ +

If you want to continue to use a MIME-type in your + hyperlinks (e.g. foo.html) the language + extension (including an encoding extension if there is one) + must be on the right hand side of the MIME-type extension + (e.g., foo.html.en).

Note on Caching

+ +

When a cache stores a representation, it associates it with + the request URL. The next time that URL is requested, the cache + can use the stored representation. But, if the resource is + negotiable at the server, this might result in only the first + requested variant being cached and subsequent cache hits might + 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.

+ +

For requests which come from a HTTP/1.0 compliant client + (either a browser or a cache), the directive CacheNegotiatedDocs 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.