7. Response Header Fields
The response header fields allow the server to pass additional information about the response beyond what is placed in the status-line. These header fields give information about the server, about further access to the target resource, or about related resources.
Although each response header field has a defined meaning, in general, the precise semantics might be further refined by the semantics of the request method and/or response status code.
7.1. Control Data
Response header fields can supply control data that supplements the status code, directs caching, or instructs the client where to go next.
7.1.1. Origination Date
7.1.1.1. Date
The "Date" header field represents the date and time at which the message was originated, having the same semantics as the Origination Date Field (orig-date) defined in Section 3.6.1 of [RFC5322]. The field value is an HTTP-date, as defined in Section 7.1.1.1 of [RFC7231].
Date = HTTP-date
An example is:
Date: Tue, 15 Nov 1994 08:12:31 GMT
When a Date header field is generated, the sender SHOULD generate its field value as the best available approximation of the date and time of message generation. In theory, the date ought to represent the moment just before the payload is generated. In practice, the date can be generated at any time during message origination.
An origin server MUST NOT send a Date header field if it does not have a clock capable of providing a reasonable approximation of the current instance in Coordinated Universal Time. An origin server MAY send a Date header field if the response is in the 1xx (Informational) or 5xx (Server Error) class of status codes. An origin server MUST send a Date header field in all other cases.
A recipient with a clock that receives a response message without a Date header field MUST record the time it was received and append a corresponding Date header field to the message's header section if it is cached or forwarded downstream.
A user agent MAY send a Date header field in a request, though generally will not do so unless it is believed to convey useful information to the server. For example, custom applications of HTTP might convey a Date if the server is expected to adjust its interpretation of the user's request based on differences between the user agent and server clocks.
7.1.1.2. HTTP-date
HTTP applications have historically allowed three different formats for the representation of date/time stamps:
Sun, 06 Nov 1994 08:49:37 GMT ; IMF-fixdate
Sunday, 06-Nov-94 08:49:37 GMT ; obsolete RFC 850 format
Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format
The first format is preferred as an Internet standard and represents a fixed-length subset of that defined by [RFC5322] (Section 3.3). The second format is in common use, but is based on the obsolete RFC 850 [RFC0850] date format and lacks a four-digit year. HTTP/1.1 clients and servers that parse the date value MUST accept all three formats (for compatibility with HTTP/1.0), though they MUST only generate the IMF-fixdate format for representing HTTP-date values in header fields.
Note: Recipients of a timestamp value in rfc850-date format, which uses a two-digit year, MUST interpret a timestamp that appears to be more than 50 years in the future as representing the most recent year in the past that had the same last two digits.
An HTTP-date value represents time as an instance of Coordinated Universal Time (UTC). The first two formats indicate UTC by the three-letter abbreviation for Greenwich Mean Time, "GMT", a predecessor of the UTC name; values in the asctime format are assumed to be in UTC. A sender that generates HTTP-date values from a local clock ought to use NTP ([RFC5905]) or some similar protocol to synchronize its clock to UTC.
Preferred format:
HTTP-date = IMF-fixdate / obs-date
IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT
; fixed length/zone/capitalization subset of the format
; see Section 3.3 of [RFC5322]
day-name = %x4D.6F.6E ; "Mon", case-sensitive
/ %x54.75.65 ; "Tue", case-sensitive
/ %x57.65.64 ; "Wed", case-sensitive
/ %x54.68.75 ; "Thu", case-sensitive
/ %x46.72.69 ; "Fri", case-sensitive
/ %x53.61.74 ; "Sat", case-sensitive
/ %x53.75.6E ; "Sun", case-sensitive
date1 = day SP month SP year
; e.g., 02 Jun 1982
day = 2DIGIT
month = %x4A.61.6E ; "Jan", case-sensitive
/ %x46.65.62 ; "Feb", case-sensitive
/ %x4D.61.72 ; "Mar", case-sensitive
/ %x41.70.72 ; "Apr", case-sensitive
/ %x4D.61.79 ; "May", case-sensitive
/ %x4A.75.6E ; "Jun", case-sensitive
/ %x4A.75.6C ; "Jul", case-sensitive
/ %x41.75.67 ; "Aug", case-sensitive
/ %x53.65.70 ; "Sep", case-sensitive
/ %x4F.63.74 ; "Oct", case-sensitive
/ %x4E.6F.76 ; "Nov", case-sensitive
/ %x44.65.63 ; "Dec", case-sensitive
year = 4DIGIT
GMT = %x47.4D.54 ; "GMT", case-sensitive
time-of-day = hour ":" minute ":" second
; 00:00:00 - 23:59:60 (leap second)
hour = 2DIGIT
minute = 2DIGIT
second = 2DIGIT
Obsolete formats:
obs-date = rfc850-date / asctime-date
rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT
date2 = day "-" month "-" 2DIGIT
; e.g., 02-Jun-82
day-name-l = %x4D.6F.6E.64.61.79 ; "Monday", case-sensitive
/ %x54.75.65.73.64.61.79 ; "Tuesday", case-sensitive
/ %x57.65.64.6E.65.73.64.61.79 ; "Wednesday", case-sensitive
/ %x54.68.75.72.73.64.61.79 ; "Thursday", case-sensitive
/ %x46.72.69.64.61.79 ; "Friday", case-sensitive
/ %x53.61.74.75.72.64.61.79 ; "Saturday", case-sensitive
/ %x53.75.6E.64.61.79 ; "Sunday", case-sensitive
asctime-date = day-name SP date3 SP time-of-day SP year
date3 = month SP ( 2DIGIT / ( SP 1DIGIT ))
; e.g., Jun 2
HTTP-date is case sensitive. A sender MUST NOT generate additional whitespace in an HTTP-date beyond that specifically included as SP in the grammar. The semantics of day-name, day, month, year, and time-of-day are the same as those defined for the Internet Message Format constructs with the corresponding name ([RFC5322], Section 3.3).
7.1.2. Location
The "Location" header field is used in some responses to refer to a specific resource in relation to the response. The type of relationship is defined by the combination of request method and status code semantics.
Location = URI-reference
The field value consists of a single URI-reference. When it has the form of a relative reference ([RFC3986], Section 4.2), the final value is computed by resolving it against the effective request URI ([RFC7230], Section 5.5).
For 201 (Created) responses, the Location value is a URI reference to a resource that identifies the primary resource created by the request. For 3xx (Redirection) responses, the Location value refers to the preferred target resource for automatically redirecting the request.
If the Location value provided in a 3xx (Redirection) response does not have a fragment component, a user agent MUST process the redirection as if the value inherits the fragment component of the URI reference used to generate the request target (i.e., the redirection inherits the original reference's fragment, if any).
For example, a GET request generated for the URI reference "http://www.example.org/~tim" might result in several redirections before ultimately arriving at "http://www.example.com/~tim/". If the first redirection is to "http://www.example.org/people/~tim", then that redirection will be to "http://www.example.org/people/~tim" and not to "http://www.example.org/people/~tim#fred".
There are circumstances in which a fragment identifier in a Location value would not be appropriate. For example, the Location header field in a 201 (Created) response is supposed to provide a URI that is specific to the created resource.
Note: Some recipients attempt to recover from Location fields that are not valid URI references. This specification does not mandate or define such processing, but does allow it for the sake of robustness. A Location field value that is an absolute-path is acceptable, but will be interpreted relative to the effective request URI.
Note: Content negotiation of the response can cause the Location value to be different from the effective request URI. If the response is cacheable, a cache can use that Location value to determine a more appropriate key for the response (see Section 4.1 of [RFC7234]).
7.1.3. Retry-After
Servers send the "Retry-After" header field to indicate how long the user agent ought to wait before making a follow-up request. When sent with a 503 (Service Unavailable) response, Retry-After indicates how long the service is expected to be unavailable to the client. When sent with a 429 (Too Many Requests) response, Retry-After indicates how long the user agent should wait before making a follow-up request. When sent with any 3xx (Redirection) response, Retry-After indicates the minimum time that the user agent is asked to wait before issuing the redirected request.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date / delay-seconds
A delay-seconds value is a non-negative decimal integer, representing time in seconds.
delay-seconds = 1*DIGIT
Two examples of its use are:
Retry-After: Fri, 31 Dec 1999 23:59:59 GMT
Retry-After: 120
In the latter example, the delay is 2 minutes.
7.1.4. Vary
The "Vary" header field in a response describes what parts of a request message, aside from the method and request target, might influence the origin server's process for selecting and representing this response. The value consists of either a single asterisk ("*") or a list of header field names (case-insensitive).
Vary = "*" / 1#field-name
A Vary field value of "" signals that anything about the request might play a role in selecting the response representation, possibly including elements outside the message syntax (e.g., the client's network address). A recipient will not be able to determine whether this response is appropriate for a later request without forwarding the request to the origin server. A proxy MUST NOT generate a Vary field with a "" value.
A Vary field value consisting of a comma-separated list of names indicates that the named request header fields, known as the selecting request header fields, might have a role in selecting the representation. The potential selecting request header fields are not limited to those defined by this specification.
For example, a response that contains:
Vary: accept-encoding, accept-language
indicates that the origin server might have used the request's Accept-Encoding and Accept-Language fields (or lack thereof) as determining factors while choosing the content for this response.
An origin server might send Vary with a list of fields for two purposes:
-
To inform cache recipients that they MUST NOT use this response to satisfy a later request unless the later request has the same values for the listed fields as the original request (Section 4.1 of [RFC7234]). In other words, Vary expands the cache key required to match a new request to the stored cache entry.
-
To inform user agent recipients that this response is subject to content negotiation (Section 3.4) and that a different representation might be sent in a subsequent request if additional parameters are provided in the listed header fields (proactive negotiation).
An origin server SHOULD send a Vary header field when its algorithm for selecting a representation varies based on aspects of the request message other than the method and request target, unless the variance cannot be crossed or the origin server has been deliberately configured to prevent cache transparency. For example, there is no need to send the Authorization field name in Vary because reuse across users is constrained by the field definition (Section 4.2 of [RFC7235]). Likewise, an origin server might use a request header field for selecting a representation that is entirely within its control (e.g., via a private header field or internal request metadata) and, in that case, would not need to advertise it in Vary.
7.2. Validator Header Fields
Validator header fields convey metadata about the selected representation (Section 3). In responses to safe methods, validator fields describe the selected representation. In responses to state-changing methods, validator fields describe the new representation that has replaced the prior selected representation as a result of successfully processing the request.
7.2.1. ETag
The "ETag" header field in a response provides the current entity-tag for the selected representation, as determined at the conclusion of handling the request. An entity-tag is an opaque validator for differentiating between multiple representations of the same resource, regardless of whether those multiple representations are due to resource state changes over time, content negotiation resulting in multiple representations being valid at the same time, or both.
ETag = entity-tag
The entity-tag grammar is defined in Section 2.3 of [RFC7232]:
entity-tag = [ weak ] opaque-tag
weak = %x57.2F ; "W/", case-sensitive
opaque-tag = DQUOTE *etagc DQUOTE
etagc = %x21 / %x23-7E / obs-text
; VCHAR except double quotes, plus obs-text
Note: Previously, opaque-tag was defined to be a quoted-string ([RFC2616], Section 3.11); thus, some recipients might perform backslash unescaping. Servers therefore ought to avoid backslash characters in entity tags.
An entity-tag can be either a weak or strong validator, with strong being the default. If an origin server provides an entity-tag for a representation and the generation of that entity-tag does not satisfy all of the characteristics of a strong validator (Section 2.1 of [RFC7232]), then the origin server MUST mark the entity-tag as weak by prefixing its opaque value with "W/" (case-sensitive).
A sender MAY send the ETag field in a trailer section (Section 4.1.2 of [RFC7230]), but this is only useful for responses that do not have a content encoding and where the user agent can compute the entity-tag prior to receiving the trailer section. When ETag is sent in the trailer section, it overrides any ETag field value that was sent in the header section.
Examples:
ETag: "xyzzy"
ETag: W/"xyzzy"
ETag: ""
An origin server SHOULD send an ETag for any selected representation for which detection of changes can be reasonably and consistently determined, since the entity-tag's use in conditional requests and evaluating cache freshness ([RFC7234]) can substantially reduce unnecessary transfers and significantly improve service availability and scalability.
7.2.2. Last-Modified
The "Last-Modified" header field in a response provides a timestamp indicating the date and time at which the origin server believes the selected representation was last modified, as determined at the conclusion of handling the request.
Last-Modified = HTTP-date
An example of its use is:
Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT
An origin server SHOULD send Last-Modified for any selected representation for which a last modification date can be reasonably and consistently determined, since its use in conditional requests and evaluating cache freshness ([RFC7234]) can substantially reduce unnecessary transfers and significantly improve service availability and scalability. A representation is typically the sum of many parts behind the resource interface. The last-modified time would usually be the most recent time that any of those parts were changed.
An origin server SHOULD obtain the Last-Modified value of the representation as close as possible to the time that it generates the Date field value for the response. This allows a recipient to make an accurate assessment of the representation's modification time, especially if the representation changes near the time that the response is generated.
An origin server with a clock (as defined in Section 7.1.1.1) MUST NOT send a Last-Modified date that is later than the server's time of message origination (Date). If the last modification time is derived from implementation-specific metadata that evaluates to some time in the future, according to the origin server's clock, then the origin server MUST replace that value with the message origination date. This prevents a future modification date from having an adverse impact on cache validation.
An origin server without a clock MUST NOT assign Last-Modified values to a response unless these values were associated with the resource by some other system with a clock or unless the values were previously received from the origin server (e.g., from a back-end database).
7.3. Authentication Challenges
Authentication challenges indicate what mechanisms are available for the client to provide authentication credentials in future requests.
7.3.1. WWW-Authenticate
The "WWW-Authenticate" header field indicates the authentication scheme(s) and parameters applicable to the target resource.
WWW-Authenticate = 1#challenge
A server generating a 401 (Unauthorized) response MUST send a WWW-Authenticate header field containing at least one challenge. A server MAY generate a WWW-Authenticate header field in other response messages to indicate that supplying credentials (or different credentials) might affect the response.
A proxy forwarding a response MUST NOT modify any WWW-Authenticate fields in that response.
User agents are advised to take special care in parsing the field value, as it might contain more than one challenge, and each challenge can contain a comma-separated list of authentication parameters. Furthermore, the header field itself can occur multiple times.
For further details, see Section 4.1 of [RFC7235].
7.3.2. Proxy-Authenticate
The "Proxy-Authenticate" header field consists of at least one challenge that indicates the authentication scheme(s) and parameters applicable to the proxy for this request-target. A proxy MUST send at least one Proxy-Authenticate header field in each 407 (Proxy Authentication Required) response that it generates.
Proxy-Authenticate = 1#challenge
Unlike WWW-Authenticate, the Proxy-Authenticate header field applies only to the next outbound client on the response chain. This is because only the client that chose a given proxy is likely to have the credentials necessary for authentication. However, when multiple proxies are used within the same administrative domain, such as office and regional caching proxies within a large corporate network, it is common for credentials to be generated by the user agent and passed through the hierarchy until consumed. Hence, in such a configuration, it will appear as if Proxy-Authenticate is being forwarded because each proxy will send the same challenge set.
For further details, see Section 4.3 of [RFC7235].
7.4. Response Context
The following response header fields provide additional information about the response, beyond what is implied by the status code, or about the server handling the response.
7.4.1. Allow
The "Allow" header field lists the set of methods advertised as supported by the target resource. The purpose of this field is strictly to inform the recipient of valid request methods associated with the resource.
Allow = #method
Example of use:
Allow: GET, HEAD, PUT
The actual set of allowed methods is defined by the origin server at the time of each request. An origin server MUST generate an Allow field in a 405 (Method Not Allowed) response and MAY do so in any other response. An empty Allow field value indicates that the resource allows no methods, which might occur in a 405 response if the resource has been temporarily disabled by configuration.
A proxy MUST NOT modify the Allow header field -- it does not need to understand all of the indicated methods in order to handle them according to the generic message handling rules.
7.4.2. Server
The "Server" header field contains information about the software used by the origin server to handle the request, which is often used by clients to help identify the scope of reported interoperability problems, to work around or tailor requests to avoid particular server limitations, and for analytics regarding server or operating system use. An origin server MAY generate a Server field in any response.
Server = product *( RWS ( product / comment ) )
The Server field-value consists of one or more product identifiers, each followed by zero or more comments (Section 3.2 of [RFC7230]), which together identify the origin server software and its significant subproducts. By convention, the product identifiers are listed in decreasing order of their significance for identifying the origin server software. Each product identifier consists of a name and optional version, as defined in Section 5.5.3 of [RFC7230].
Example:
Server: CERN/3.0 libwww/2.17
An origin server SHOULD NOT generate a Server field containing needlessly fine-grained detail and SHOULD limit the addition of subproducts by third parties. Overly long and detailed Server field values increase response latency and potentially reveal internal implementation details that might make it (slightly) easier for attackers to find and exploit known security holes.