Book HomeWebmaster in a Nutshell, 3rd EditionSearch this book

17.3. HTTP Headers

HTTP headers are used to transfer all sorts of information between client and server. There are four categories of headers:

General
Information not related to the client, server, or HTTP

Request
Preferred document formats and server parameters

Response
Information about the server sending the response

Entity
Information on the data being sent between the client and server

General headers and entity headers are the same for both the server and client.

All headers in HTTP messages contain the header name followed by a colon (:), then a space, and the value of the header. Header names are case-insensitive (thus, Content-Type is the same as Content-type). The value of a header can extend over multiple lines by preceding each extra line with at least one space or tab character.

17.3.1. General Headers

General headers are used in both client requests and server responses. Some may be more specific to either a client or server message.

Cache-Control

Cache-Control: directives

Specifies caching directives in a comma-separated list.

Cache Request Directives

no-cache 2n
Do not cache.

no-store
Remove information promptly after forwarding.

max-age = seconds
Do not send responses older than seconds.

max-stale [ = seconds ]
Send expired data. If seconds are specified, only send data expired by less than the specified number of seconds.

min-fresh = seconds
Send data only if still fresh after the specified number of seconds.

only-if-cached
Do not retrieve new data. Only return data already in the cache. Useful unless the network connection is down.

Cache Response Directives

public
Cachable by any cache.

private
Not cachable by a shared cache.

no-cache
Do not cache.

no-store
Remove information promptly after forwarding.

no-transform
Do not convert data.

must-revalidate
Client must revalidate the data.

proxy-revalidate
Client must revalidate data except for private client caches.

max-age=seconds
The document should be considered stale in the specified number of seconds.

Connection

Connection: options

Specifies options desired for this connection but not for further connections by proxies. The close connection option signifies that either the client or server wishes to end the connection (i.e., this is the last transaction).

Date

Date: dateformat

Indicates the current date and time. The preferred date format is described by RFC 1123. For example:

Mon, 06 May 1999 04:57:00 GMT

For backward compatibility, however, the RFC-850 and ANSI C asctime( ) formats are also acceptable:

Monday, 06-May-99 04:57:00 GMT
Mon May 6 04:57:00 1999

Use a two-digit year specification at your own risk.

MIME-Version

MIME-Version:version

Specifies the version of MIME (RFC-2045[7]) used in the HTTP transaction. If a message's entity-body does not conform to MIME, this header can be omitted. If the transaction involves MIME-encoded data, but this header is omitted, the default value is assumed to be 1.0.

Pragma

Pragma: no-cache 

Specifies directives to a proxy system. This header is ignored by the target server. HTTP defines one directive for this header: no-cache. In HTTP 1.0, this tells the proxy to request the document from the server instead of the local cache. HTTP 1.1 prefers using Cache Control: no-cache instead.

Transfer-Encoding

Transfer-Encoding: encoding_type

Indicates what type of transformation has been applied to the message body for safe transfer. Currently only the chunked encoding type is defined by HTTP.

Upgrade

Upgrade: protocol/version

Specifies the preferred communication protocols. Used in conjunction with response code 101 Switching Protocols. For example:

Upgrade: HTTP/1.2
Via

Via: protocol host [comment] ...

Used by gateways and proxies to indicate the protocols and hosts that processed the transaction between client and server.

17.3.2. Client Request Headers

Client header data communicates the client's configuration and preferred document formats to the server. Request headers are used in a client message to provide information about the client.

Accept

Accept: type/subtype [; q=qvalue]

Specifies media types that the client prefers to accept. Multiple media types can be listed, separated by commas. The optional qvalue represents on a scale of 0 to 1 an acceptable quality level for accept types. Media types are listed at the end of this chapter.

Accept-Charset

Accept-Charset: character_set  [; q=qvalue]

Specifies the character sets the client prefers. Multiple character sets can be listed separated by commas. The optional qvalue represents on a scale of 0 to 1 an acceptable quality level for nonpreferred character sets.

Accept-Encoding

Accept-Encoding: encoding_types

Specifies the encoding schemes the client can accept, such as compress or gzip. Multiple encoding schemes can be listed, separated by commas. If no encoding types are listed, none are acceptable to the client.

Accept-Language

Accept-Language: language [; q=qvalue]

Specifies the languages the client prefers. Multiple languages can be listed, separated by commas. The optional qvalue represents on a scale of 0 to 1 an acceptable quality level for nonpreferred languages. Languages are written with their two-letter abbreviations (e.g., en for English, de for German, fr for French, etc.).

Authorization

Authorization: scheme credentials

Provides the client's authorization to access data at a URI. When a requested document requires authorization, the server returns a WWW-Authenticate header describing the type of authorization required. The client then repeats the request with the proper authorization information.

The authorization scheme generally used in HTTP is BASIC, and under the BASIC scheme the credentials follow the format username:password encoded in base64. For example, for the username "webmaster" and a password "zrma4v," the authorization header would look like this:

Authorization: BASIC d2VibWFzdGVyOnpycW1hNHY=

The value decodes into webmaster:zrma4v.

Cookie

Cookie: name=value

Contains a name/value pair of information stored for that URL. Multiple cookies can be specified, separated by semicolons. For browsers supporting Netscape persistent cookies; not included in the HTTP standard. See the discussion of cookies later in this chapter for more information.

From

From: email_address

Gives the email address of the user executing the client.

Host

Host: hostname[:port]

Specifies the host and port number of the URI. Clients must supply this information in HTTP 1.1, so servers with multiple hostnames can easily differentiate between ambiguous URLs.

If-Modified-Since

If-Modified-Since: date

Specifies that the URI data is to be sent only if it has been modified since the date given as the value of this header. This is useful for client-side caching. If the document has not been modified, the server returns a code of 304, indicating that the client should use the local copy. The specified date should follow the format described under the Date header.

If-Match

If-Match: entity_tag

A conditional requesting the entity only if it matches the given entity tags (see the ETag entity header). An asterisk (*) matches any entity, and the transaction continues only if the entity exists.

If-None-Match

If-None-Match: entity_tag

A conditional requesting the entity only if it does not match any of the given entity tags (see the ETag entity header). An asterisk (*) matches any entity; if the entity doesn't exist, the transaction continues.

If-Range

If-Range: entity_tag | date

A conditional requesting only the portion of the entity that is missing if it has not been changed, and the entire entity if it has. Must be used in conjunction with a Range header. Either an entity tag or a date can identify the partial entity already received; see the Date header for information on the format for dates.

If-Unmodified-Since

If-Unmodified-Since: date

Specifies that the URI data is to be sent only if it has not been modified since the given date. The specified date should follow the format described under the Date header.

Max-Forwards

Max-Forwards: n

Limits the number of proxies or gateways that can forward the request. Useful for debugging with the TRACE method, avoiding infinite loops.

Proxy-Authorization

Proxy-Authorization: credentials

Used for a client to identify itself to a proxy requiring authorization.

Range

Range: bytes=n-m

Specifies the partial range(s) requested from the document. Multiple ranges can be listed, separated by commas. If the first digit in the comma-separated byte range(s) is missing, the range is assumed to count from the end of the document. If the second digit is missing, the range is byte n to the end of the document. The first byte is byte 0.

Referer

Referer: url

Gives the URI of the document that refers to the requested URI (i.e., the source document of the link).

User-Agent

User-Agent: string

Gives identifying information about the client program.

17.3.3. Server Response Headers

The response headers described here are used in server responses to communicate information about the server and how it may handle requests.

Accept-Ranges

Accept-Ranges: bytes|none

Indicates the acceptance of range requests for a URI, specifying either the range unit (e.g., bytes), or none if no range requests are accepted.

Age

Age: seconds

Indicates the age of the document in seconds.

Proxy-Authenticate

Proxy-Authenticate: scheme realm

Indicates the authentication scheme and parameters applicable to the proxy for this URI and the current connection. Used with response 407 (Proxy Authentication Required).

Retry-After

Retry-After: date|seconds

Used with response code 503 (Service Unavailable). It contains either an integer number of seconds or a GMT date and time (as described by the Date header formats). If the value is an integer, it is interpreted as the number of seconds to wait after the request was issued. For example:

Retry-After: 3600
Retry-After: Sat, 18 May 1996 06:59:37 GMT
Server

Server: string

Contains the name and version number of the server. For example:

Server: NCSA/1.3
Set-Cookie

Set-Cookie: name=value [; options]

Contains a name/value pair of information to retain for this URL. For browsers supporting Netscape persistent cookies; not included in the HTTP standard. See Section 17.4 for more information. Options are:

expires=date 2n
The cookie becomes invalid after the specified date.

path=pathname
The URL range for which the cookie is valid.

domain=domain_name
The domain name range for which the cookie is valid.

secure
Return the cookie only under a secure connection.

Vary

Vary: *| headers

Specifies that the entity has multiple sources and may therefore vary according to a specified list of request header(s). Multiple headers can be listed, separated by commas. An asterisk (*) means that another factor other than the request headers may affect the document that is returned.

Warning

Warning: code host[:port] string

Indicates additional information to that in the status code, for use by caching proxies. The host field contains the name or pseudonym of the server host, with an optional port number. The two-digit warning codes and their recommended descriptive strings are:

10 Response is stale 2n
The response data is known to be stale.

11 Revalidation failed 2n
The response data is known to be stale because the proxy failed to revalidate the data.

12 Disconnected operation 2n
The cache is disconnected from the network.

13 Heuristic expiration 2n
The data is older than 24 hours, and the cache heuristically chose a freshness lifetime greater than 24 hours.

14 Transformation applied 2n
The proxy has changed the encoding or media type of the document, as specified by the Content-Encoding or Content-Type headers.

99 Miscellaneous warning 2n
Arbitrary information to be logged or presented to the user.

WWW-Authenticate

WWW-Authenticate: scheme realm

Used with the 401 (Unauthorized) response code. It specifies the authorization scheme and realm of authorization required from a client at the requested URI. Many different authorization realms can exist on a server. A common authorization scheme is BASIC, which requires a username and password. For example:

WWW-Authenticate: BASIC realm="Admin"

When returned to the client, this header indicates that the BASIC type of authorization data in the appropriate realm should be returned in the client's Authorization header.

17.3.4. Entity Headers

Entity headers are used in both client requests and server responses. They supply information about the entity body in an HTTP message.

Allow

Allow: methods

Contains a comma-separated list of methods that are allowed at a specified URI. In a server response, it is used with code 405 (Method Not Allowed) to inform the client of valid methods available for the requested information.

Content-Encoding

Content-Encoding: encoding_schemes

Specifies the encoding scheme(s) used for the transferred entity body. Values are gzip (or x-gzip) and compress (or x-compress). If multiple encoding schemes are specified (in a comma-separated list), they must be listed in the order in which they were applied to the source data.

Content-Language

Content-Language: languages

Specifies the language(s) the transferred entity body is intended for. Languages are represented by their two-digit code (e.g., en for English, fr for French).

Content-Length

Content-Length: n

This header specifies the length of the data (in bytes) of the transferred entity body. Due to the dynamic nature of some requests, the content length is sometimes unknown, and this header is omitted.

Content-Location

Content-Location: uri

Supplies the URI for the entity, in cases where a document has multiple entities with separately accessible locations. The URI can be either absolute or relative.

Content-MD5

Content-MD5: digest

Supplies a MD5 digest of the entity, for checking the integrity of the message upon receipt.

Content-Range

Content-Range: bytes n-m/length

Specifies where the accompanying partial entity body should be inserted and the total size of the full entity body. For example:

Content-Range: bytes 6143-7166/15339
Content-Transfer-Encoding

Content-Transfer-Encoding: scheme

Specifies any transformations that are applied to the entity body for transport over a network. Common values are: 7bit, 8bit, binary, base64, and quoted-printable.

Content-Type

Content-Type: type/subtype

Describes the media type and subtype of an entity body. It uses the same values as the client's Accept header, and the server should return media types that conform with the client's preferred formats.

ETag

ETag: entity_tag

Defines the entity tag for the If-Match and If-None-Match request headers.

Expires

Expires: date

Specifies the time when a document may change, or its information becomes invalid. After that time, the document may or may not change or be deleted. The value is a date and time in a valid format, as described for the Date header.

Last-Modified

Last-Modified: date

Specifies when the specified URI was last modified. The value is a date and time in a valid format, as described for the Date header.

Location

Location: uri

Specifies the new location of a document, usually with response codes 201 (Created), 301 (Moved Permanently), or 302 (Moved Temporarily). The URI given must be written as an absolute URI.



Library Navigation Links

Copyright © 2003 O'Reilly & Associates. All rights reserved.