- 1) Introduction
- 2) Notational Conventions and Generic Grammar
- 3) Protocol Parameters
- 1) HTTP Version
- 2) Uniform Resource Identifiers
- 3) Date/Time Formats
- 4) Character Sets
- 5) Content Codings
- 6) Transfer Codings
- 7) Media Types
- 8) Product Tokens
- 9) Quality Values
- 10) Language Tags
- 11) Entity Tags
- 12) Range Units
- 4) HTTP Message
- 5) Request
- 6) Response
- 7) Entity
- 8) Connections
- 1) Persistent Connections
- 2) Message Transmission Requirements
- 9) Method Definitions
- 10) Status Code Definitions
- 1) Informational 1xx
- 2) Successful 2xx
- 3) Redirection 3xx
- 4) Client Error 4xx
- 1) 400 Bad Request
- 2) 401 Unauthorized
- 3) 402 Payment Required
- 4) 403 Forbidden
- 5) 404 Not Found
- 6) 405 Method Not Allowed
- 7) 406 Not Acceptable
- 8) 407 Proxy Authentication Required
- 9) 408 Request Timeout
- 10) 409 Conflict
- 11) 410 Gone
- 12) 411 Length Required
- 13) 412 Precondition Failed
- 14) 413 Request Entity Too Large
- 15) 414 Request-URI Too Long
- 16) 415 Unsupported Media Type
- 17) 416 Requested Range Not Satisfiable
- 18) 417 Expectation Failed
- 5) Server Error 5xx
- 11) Access Authentication
- 12) Content Negotiation
- 13) Caching in HTTP
- 1) ..
- 2) Expiration Model
- 3) Validation Model
- 4) Response Cacheability
- 5) Constructing Responses From Caches
- 6) Caching Negotiated Responses
- 7) Shared and Non-Shared Caches
- 8) Errors or Incomplete Response Cache Behavior
- 9) Side Effects of GET and HEAD
- 10) Invalidation After Updates or Deletions
- 11) Write-Through Mandatory
- 12) Cache Replacement
- 13) History Lists
- 14) Header Field Definitions
- 1) Accept
- 2) Accept-Charset
- 3) Accept-Encoding
- 4) Accept-Language
- 5) Accept-Ranges
- 6) Age
- 7) Allow
- 8) Authorization
- 9) Cache-Control
- 10) Connection
- 11) Content-Encoding
- 12) Content-Language
- 13) Content-Length
- 14) Content-Location
- 15) Content-MD5
- 16) Content-Range
- 17) Content-Type
- 18) Date
- 19) ETag
- 20) Expect
- 21) Expires
- 22) From
- 23) Host
- 24) If-Match
- 25) If-Modified-Since
- 26) If-None-Match
- 27) If-Range
- 28) If-Unmodified-Since
- 29) Last-Modified
- 30) Location
- 31) Max-Forwards
- 32) Pragma
- 33) Proxy-Authenticate
- 34) Proxy-Authorization
- 35) Range
- 36) Referer
- 37) Retry-After
- 38) Server
- 39) TE
- 40) Trailer
- 41) Transfer-Encoding
- 42) Upgrade
- 43) User-Agent
- 44) Vary
- 45) Via
- 46) Warning
- 47) WWW-Authenticate
- 15) Security Considerations
- 1) Personal Information
- 2) Attacks Based On File and Path Names
- 3) DNS Spoofing
- 4) Location Headers and Spoofing
- 5) Content-Disposition Issues
- 6) Authentication Credentials and Idle Clients
- 7) Proxies and Caching
- 16) Acknowledgments
- 17) References
- 18) Authors' Addresses
- 19) Appendices
- 1) Internet Media Type message/http and application/http
- 2) Internet Media Type multipart/byteranges
- 3) Tolerant Applications
- 4) Differences Between HTTP Entities and RFC 2045 Entities
- 5) Additional Features
- 6) Compatibility with Previous Versions
- 20) Index
- 21) Full Copyright Statement
- 22) Acknowledgement
HTTP is typically used for distributed information systems, where performance can be improved by the use of response caches. The HTTP/1.1 protocol includes a number of elements intended to make caching work as well as possible. Because these elements are inextricable from other aspects of the protocol, and because they interact with each other, it is useful to describe the basic caching design of HTTP separately from the detailed descriptions of methods, headers, response codes, etc.
Caching would be useless if it did not significantly improve performance. The goal of caching in HTTP/1.1 is to eliminate the need to send requests in many cases, and to eliminate the need to send full responses in many other cases. The former reduces the number of network round-trips required for many operations; we use an "expiration" mechanism for this purpose (see Section 13.2). The latter reduces network bandwidth requirements; we use a "validation" mechanism for this purpose (see Section 13.3).
Requirements for performance, availability, and disconnected operation require us to be able to relax the goal of semantic transparency. The HTTP/1.1 protocol allows origin servers, caches, and clients to explicitly reduce transparency when necessary. However, because non-transparent operation may confuse non-expert users, and might be incompatible with certain server applications (such as those for ordering merchandise), the protocol requires that transparency be relaxed
- only by an explicit protocol-level request when relaxed by client or origin server
- only with an explicit warning to the end user when relaxed by cache or client
Therefore, the HTTP/1.1 protocol provides these important elements:
Protocol features that provide full semantic transparency when this is required by all parties.
Protocol features that allow an origin server or user agent to explicitly request and control non-transparent operation.
Protocol features that allow a cache to attach warnings to responses that do not preserve the requested approximation of semantic transparency.
A basic principle is that it must be possible for the clients to detect any potential relaxation of semantic transparency.
Note: The server, cache, or client implementor might be faced with design decisions not explicitly discussed in this specification. If a decision might affect semantic transparency, the implementor ought to err on the side of maintaining transparency unless a careful and complete analysis shows significant benefits in breaking transparency.
13.1.1 Cache Correctness
A correct cache MUST respond to a request with the most up-to-date response held by the cache that is appropriate to the request (see Sections 13.2.5, 13.2.6, and 13.12) which meets one of the following conditions:
It has been checked for equivalence with what the origin server would have returned by revalidating the response with the origin server (Section 13.3);
It is "fresh enough" (see Section 13.2). In the default case, this means it meets the least restrictive freshness requirement of the client, origin server, and cache (see Section 14.9); if the origin server so specifies, it is the freshness requirement of the origin server alone.
If a stored response is not "fresh enough" by the most restrictive freshness requirement of both the client and the origin server, in carefully considered circumstances the cache MAY still return the response with the appropriate Warning header (see Section 13.1.5 and 14.46), unless such a response is prohibited (e.g., by a "no-store" cache-directive, or by a "no-cache" cache-request-directive; see Section 14.9).
It is an appropriate 304 (Not Modified), 305 (Proxy Redirect), or error (4xx or 5xx) response message.
If the cache can not communicate with the origin server, then a correct cache SHOULD respond as above if the response can be correctly served from the cache; if not it MUST return an error or warning indicating that there was a communication failure.
If a cache receives a response (either an entire response, or a 304 (Not Modified) response) that it would normally forward to the requesting client, and the received response is no longer fresh, the cache SHOULD forward it to the requesting client without adding a new Warning (but without removing any existing Warning headers). A cache SHOULD NOT attempt to revalidate a response simply because that response became stale in transit; this might lead to an infinite loop. A user agent that receives a stale response without a Warning MAY display a warning indication to the user.
Whenever a cache returns a response that is neither first-hand nor "fresh enough" (in the sense of condition 2 in Section 13.1.1), it MUST attach a warning to that effect, using a Warning general-header. The Warning header and the currently defined warnings are described in Section 14.46. The warning allows clients to take appropriate action.
Warnings MAY be used for other purposes, both cache-related and otherwise. The use of a warning, rather than an error status code, distinguish these responses from true failures.
Warnings are assigned three digit warn-codes. The first digit indicates whether the Warning MUST or MUST NOT be deleted from a stored cache entry after a successful revalidation:
1xx Warnings that describe the freshness or revalidation status of the response, and so MUST be deleted after a successful revalidation. 1XX warn-codes MAY be generated by a cache only when validating a cached entry. It MUST NOT be generated by clients.
2xx Warnings that describe some aspect of the entity body or entity headers that is not rectified by a revalidation (for example, a lossy compression of the entity bodies) and which MUST NOT be deleted after a successful revalidation.
See Section 14.46 for the definitions of the codes themselves.
HTTP/1.0 caches will cache all Warnings in responses, without deleting the ones in the first category. Warnings in responses that are passed to HTTP/1.0 caches carry an extra warning-date field, which prevents a future HTTP/1.1 recipient from believing an erroneously cached Warning.
Warnings also carry a warning text. The text MAY be in any appropriate natural language (perhaps based on the client's Accept headers), and include an OPTIONAL indication of what character set is used.
Multiple warnings MAY be attached to a response (either by the origin server or by a cache), including multiple warnings with the same code number. For example, a server might provide the same warning with texts in both English and Basque.
When multiple warnings are attached to a response, it might not be practical or reasonable to display all of them to the user. This version of HTTP does not specify strict priority rules for deciding which warnings to display and in what order, but does suggest some heuristics.
13.1.3 Cache-control Mechanisms
The basic cache mechanisms in HTTP/1.1 (server-specified expiration times and validators) are implicit directives to caches. In some cases, a server or client might need to provide explicit directives to the HTTP caches. We use the Cache-Control header for this purpose.
The Cache-Control header allows a client or server to transmit a variety of directives in either requests or responses. These directives typically override the default caching algorithms. As a general rule, if there is any apparent conflict between header values, the most restrictive interpretation is applied (that is, the one that is most likely to preserve semantic transparency). However, in some cases, cache-control directives are explicitly specified as weakening the approximation of semantic transparency (for example, "max-stale" or "public").
The cache-control directives are described in detail in Section 14.9.
13.1.4 Explicit User Agent Warnings
Many user agents make it possible for users to override the basic caching mechanisms. For example, the user agent might allow the user to specify that cached entities (even explicitly stale ones) are never validated. Or the user agent might habitually add "Cache- Control: max-stale=3600" to every request. The user agent SHOULD NOT default to either non-transparent behavior, or behavior that results in abnormally ineffective caching, but MAY be explicitly configured to do so by an explicit action of the user.
If the user has overridden the basic caching mechanisms, the user agent SHOULD explicitly indicate to the user whenever this results in the display of information that might not meet the server's transparency requirements (in particular, if the displayed entity is known to be stale). Since the protocol normally allows the user agent to determine if responses are stale or not, this indication need only be displayed when this actually happens. The indication need not be a dialog box; it could be an icon (for example, a picture of a rotting fish) or some other indicator.
If the user has overridden the caching mechanisms in a way that would abnormally reduce the effectiveness of caches, the user agent SHOULD continually indicate this state to the user (for example, by a display of a picture of currency in flames) so that the user does not inadvertently consume excess resources or suffer from excessive latency.
13.1.5 Exceptions to the Rules and Warnings
In some cases, the operator of a cache MAY choose to configure it to return stale responses even when not requested by clients. This decision ought not be made lightly, but may be necessary for reasons of availability or performance, especially when the cache is poorly connected to the origin server. Whenever a cache returns a stale response, it MUST mark it as such (using a Warning header) enabling the client software to alert the user that there might be a potential problem.
It also allows the user agent to take steps to obtain a first-hand or fresh response. For this reason, a cache SHOULD NOT return a stale response if the client explicitly requests a first-hand or fresh one, unless it is impossible to comply for technical or policy reasons.
13.1.6 Client-controlled Behavior
While the origin server (and to a lesser extent, intermediate caches, by their contribution to the age of a response) are the primary source of expiration information, in some cases the client might need to control a cache's decision about whether to return a cached response without validating it. Clients do this using several directives of the Cache-Control header.
A client's request MAY specify the maximum age it is willing to accept of an unvalidated response; specifying a value of zero forces the cache(s) to revalidate all responses. A client MAY also specify the minimum time remaining before a response expires. Both of these options increase constraints on the behavior of caches, and so cannot further relax the cache's approximation of semantic transparency.
A client MAY also specify that it will accept stale responses, up to some maximum amount of staleness. This loosens the constraints on the caches, and so might violate the origin server's specified constraints on semantic transparency, but might be necessary to support disconnected operation, or high availability in the face of poor connectivity.