Best Practice: Use File Extensions on URIs to Request Representations in Specific Content Types

State: Approved

Contact: Arthur Ryman

Scope

Multiple Representations of Resources

A web resource may, in general, have many representations. For example, a Linked Data resource may have representations as HTML, RDF/XML, and Turtle media types. The existence of multiple representations is useful since it allows the client to request the most suitable one. For example, a human client may prefer HTML whereas a programmatic agent may prefer RDF/XML. HTTP clients can indicate the preferred representation using the mechanism known as Content Negotiation which is based on the use of HTTP headers. For example, the Accept header allows the client to request its preferred media type.

Although the use of HTTP headers provides a complete solution to the problem of content negotiation, in some situations it more convenient to request a specific media type using a related URI. The use of related URIs means that users can use standard web browsers to request specific media types. Also, these related URIs can be used as hyperlinks in web pages.

Recommendation

Specific URIs Related to Generic URIs

In the following, a URI that identifies a resource that has representations in multiple media types is referred to as a generic URI, and a URI that identifies a resource that has representations in exactly one media type is referred to as a specific URI. Note that a specific URI may have multiple representations, e.g. as different national languages, character encodings, and compressions, but all of these have the same media type.

A specific URI is related to a generic URI when the representations of the specific URI are a subset of the representations of the generic URI. Note that a specific URI and its related generic URI identify distinct resources. These distinct resources are closely related since they share some representations.

Use IANA File Extensions in Specific URIs

From a usability viewpoint, it is desirable if specific URIs are constructed from generic URIs using an easily understood pattern, e.g. by appending a query string or suffix. This Best Practice recommends that specific URIs be constructed by appending a file extension to the generic URI. The use of file extensions to indicate media type is commonly used in operating systems. Furthermore, when a media type is registered with IANA, a preferred file extension is specified. The IANA file extension should be used when constructing specific URIs.

Do Not Redirect Requests

Since a specific URI and its related generic URI identify distinct resources, HTTP requests for one must not be redirected to the other. For example, the following HTTP request

GET /resource/42
Accept: text/html

MUST NOT 3xx redirect to /resource/42.html or respond with Resource URI /resource/42.html.

Use Content-Location

There are two relevant HTTP response headers, Location and Content-Location. Location is used with redirects, but we recommend NOT to use redirects. Content-Location SHOULD be used to provide the URI of the variant of a resource that is being returned in the response. So in the example the server should set the Content-Location header to /resource/42.html. See RFC 2616, Header Field Definitions for the definition of Content-Location.

Examples

For example, consider the following generic URI: http://example.com/resource/42. The following table lists some related specific URIs and their media types:

See Also

• Internet Assigned Numbers Authority
• RFC 2616, Header Field Definitions