content-negotiation.xml revision c68aa7f213d409d464eaa6b963afb28678548f4f
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere<!-- $LastChangedRevision$ -->
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere Licensed to the Apache Software Foundation (ASF) under one or more
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere contributor license agreements. See the NOTICE file distributed with
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere this work for additional information regarding copyright ownership.
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere The ASF licenses this file to You under the Apache License, Version 2.0
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen (the "License"); you may not use this file except in compliance with
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen the License. You may obtain a copy of the License at
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere Unless required by applicable law or agreed to in writing, software
d229f940abfb2490dee17979e9a5ff31b7012eb5rbowen distributed under the License is distributed on an "AS IS" BASIS,
3f08db06526d6901aa08c110b5bc7dde6bc39905nd WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere See the License for the specific language governing permissions and
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere limitations under the License.
fac8c35bfb158112226ab43ddf84d59daca5dc30nd <p>Apache HTTPD supports content negotiation as described in
d474d8ef01ec5c2a09341cd148851ed383c3287crbowen representation of a resource based on the browser-supplied
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere preferences for media type, languages, character set and
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere encoding. It also implements a couple of features to give
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere more intelligent handling of requests from browsers that send
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere incomplete negotiation information.</p>
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere <p>Content negotiation is provided by the
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere <module>mod_negotiation</module> module, which is compiled in
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor by default.</p>
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor<section id="about"><title>About Content Negotiation</title>
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere <p>A resource may be available in several different
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere representations. For example, it might be available in
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere different languages or different media types, or a combination.
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere One way of selecting the most appropriate choice is to give the
fabd4bc0c499704e644a74f78cc3871436824ea0jim user an index page, and let them select. However it is often
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere possible for the server to choose automatically. This works
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere because browsers can send, as part of each request, information
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere about what representations they prefer. For example, a browser
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere could indicate that it would like to see information in French,
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere if possible, else English will do. Browsers indicate their
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor preferences by headers in the request. To request only French
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere representations, the browser would send</p>
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere <p>Note that this preference will only be applied when there is
fabd4bc0c499704e644a74f78cc3871436824ea0jim a choice of representations and they vary by language.</p>
bed3c2e56e8f3328e780200466b9d009093db468sf <p>As an example of a more complex request, this browser has
bed3c2e56e8f3328e780200466b9d009093db468sf been configured to accept French and English, but prefer
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere French, and to accept various media types, preferring HTML over
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere plain text or other text types, and preferring GIF or JPEG over
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere other media types, but also allowing any other media type as a
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere last resort:</p>
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere Accept-Language: fr; q=1.0, en; q=0.5<br />
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere 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
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor <p>httpd supports 'server driven' content negotiation, as
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere defined in the HTTP/1.1 specification. It fully supports the
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor <code>Accept-Charset</code> and<code>Accept-Encoding</code>
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere request headers. httpd also supports 'transparent'
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere content negotiation, which is an experimental negotiation
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere protocol defined in RFC 2295 and RFC 2296. It does not offer
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere support for 'feature negotiation' as defined in these RFCs.</p>
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere <p>A <strong>resource</strong> is a conceptual entity
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere identified by a URI (RFC 2396). An HTTP server like Apache HTTP Server
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere provides access to <strong>representations</strong> of the
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere resource(s) within its namespace, with each representation in
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere the form of a sequence of bytes with a defined media type,
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere character set, encoding, etc. Each resource may be associated
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere with zero, one, or more than one representation at any given
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor time. If multiple representations are available, the resource
fabd4bc0c499704e644a74f78cc3871436824ea0jim is referred to as <strong>negotiable</strong> and each of its
fabd4bc0c499704e644a74f78cc3871436824ea0jim representations is termed a <strong>variant</strong>. The ways
4126704c4950bfd46d32ad54e3b106ac6d868a73sf in which the variants for a negotiable resource vary are called
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere<section id="negotiation"><title>Negotiation in httpd</title>
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor <p>In order to negotiate a resource, the server needs to be
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor given information about each of the variants. This is done in
fabd4bc0c499704e644a74f78cc3871436824ea0jim one of two ways:</p>
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor <li>Using a type map (<em>i.e.</em>, a <code>*.var</code>
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor file) which names the files containing the variants
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor explicitly, or</li>
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor <li>Using a 'MultiViews' search, where the server does an
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor implicit filename pattern match and chooses from among the
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor results.</li>
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor <section id="type-map"><title>Using a type-map file</title>
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor <p>A type map is a document which is associated with the handler
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor named <code>type-map</code> (or, for backwards-compatibility with
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor older httpd configurations, the <glossary>MIME-type</glossary>
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor <code>application/x-type-map</code>). Note that to use this
fabd4bc0c499704e644a74f78cc3871436824ea0jim feature, you must have a handler set in the configuration that
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor defines a file suffix as <code>type-map</code>; this is best done
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere <p>Type map files should have the same name as the resource
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere which they are describing, and have an entry for each available
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere variant; these entries consist of contiguous HTTP-format header
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere lines. Entries for different variants are separated by blank
9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf lines. Blank lines are illegal within an entry. It is
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere conventional to begin a map file with an entry for the combined
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere entity as a whole (although this is not required, and if
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor present will be ignored). An example map file is shown below.
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor This file would be named <code>foo.var</code>, as it describes
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor URI: foo<br />
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere Content-language: en<br />
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor Content-language: fr, de<br />
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor <p>Note also that a typemap file will take precedence over the
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor filename's extension, even when Multiviews is on. If the
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor variants have different source qualities, that may be indicated
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor by the "qs" parameter to the media type, as in this picture
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor (available as JPEG, GIF, or ASCII-art): </p>
999942e8e84bcae9b439ab30a040b1b997b343c9gryzor URI: foo<br />
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh <p>qs values can vary in the range 0.000 to 1.000. Note that
ba543b319188dc1887607f6d59feddc00e38eee2humbedooh any variant with a qs value of 0.000 will never be chosen.
0d0ba3a410038e179b695446bb149cce6264e0abnd Variants with no 'qs' parameter value are given a qs factor of
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh 1.0. The qs parameter indicates the relative 'quality' of this
0d0ba3a410038e179b695446bb149cce6264e0abnd variant compared to the other available variants, independent
0d0ba3a410038e179b695446bb149cce6264e0abnd of the client's capabilities. For example, a JPEG file is
0d0ba3a410038e179b695446bb149cce6264e0abnd usually of higher source quality than an ASCII file if it is
0d0ba3a410038e179b695446bb149cce6264e0abnd attempting to represent a photograph. However, if the resource
0d0ba3a410038e179b695446bb149cce6264e0abnd being represented is an original ASCII art, then an ASCII
0d0ba3a410038e179b695446bb149cce6264e0abnd representation would have a higher source quality than a JPEG
0d0ba3a410038e179b695446bb149cce6264e0abnd representation. A qs value is therefore specific to a given
0d0ba3a410038e179b695446bb149cce6264e0abnd variant depending on the nature of the resource it
0d0ba3a410038e179b695446bb149cce6264e0abnd represents.</p>
0d0ba3a410038e179b695446bb149cce6264e0abnd <p>The full list of headers recognized is available in the <a
0d0ba3a410038e179b695446bb149cce6264e0abnd href="mod/mod_negotiation.html#typemaps">mod_negotation
0d0ba3a410038e179b695446bb149cce6264e0abnd <p><code>MultiViews</code> is a per-directory option, meaning it
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd can be set with an <directive module="core">Options</directive>
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd type="section">Directory</directive>, <directive module="core"
e3659090e9bb9934465dbb6c6212ba4c512190b0jfclere type="section">Location</directive> or <directive module="core"