| 2850 | | |
| 2851 | | <section title="Method Definitions" anchor="method.definitions"> |
| 2852 | | <t> |
| 2853 | | The set of common methods for HTTP/1.1 is defined below. Although |
| 2854 | | this set can be expanded, additional methods cannot be assumed to |
| 2855 | | share the same semantics for separately extended clients and servers. |
| 2856 | | |
| 2857 | | The Host request-header field (<xref target="header.host"/>) &MUST; accompany all |
| 2858 | | HTTP/1.1 requests. |
| 2859 | | </t> |
| 2860 | | |
| 2861 | | <section title="Safe and Idempotent Methods" anchor="safe.and.idempotent"> |
| 2862 | | |
| 2863 | | <section title="Safe Methods" anchor="safe.methods"> |
| 2864 | | <t> |
| 2865 | | Implementors should be aware that the software represents the user in |
| 2866 | | their interactions over the Internet, and should be careful to allow |
| 2867 | | the user to be aware of any actions they might take which may have an |
| 2868 | | unexpected significance to themselves or others. |
| 2869 | | </t> |
| 2870 | | <t> |
| 2871 | | In particular, the convention has been established that the GET and |
| 2872 | | HEAD methods &SHOULD-NOT; have the significance of taking an action |
| 2873 | | other than retrieval. These methods ought to be considered "safe". |
| 2874 | | This allows user agents to represent other methods, such as POST, PUT |
| 2875 | | and DELETE, in a special way, so that the user is made aware of the |
| 2876 | | fact that a possibly unsafe action is being requested. |
| 2877 | | </t> |
| 2878 | | <t> |
| 2879 | | Naturally, it is not possible to ensure that the server does not |
| 2880 | | generate side-effects as a result of performing a GET request; in |
| 2881 | | fact, some dynamic resources consider that a feature. The important |
| 2882 | | distinction here is that the user did not request the side-effects, |
| 2883 | | so therefore cannot be held accountable for them. |
| 2884 | | </t> |
| 2885 | | </section> |
| 2886 | | |
| 2887 | | <section title="Idempotent Methods" anchor="idempotent.methods"> |
| 2888 | | <t> |
| 2889 | | Methods can also have the property of "idempotence" in that (aside |
| 2890 | | from error or expiration issues) the side-effects of N > 0 identical |
| 2891 | | requests is the same as for a single request. The methods GET, HEAD, |
| 2892 | | PUT and DELETE share this property. Also, the methods OPTIONS and |
| 2893 | | TRACE &SHOULD-NOT; have side effects, and so are inherently idempotent. |
| 2894 | | </t> |
| 2895 | | <t> |
| 2896 | | However, it is possible that a sequence of several requests is non-idempotent, |
| 2897 | | even if all of the methods executed in that sequence are |
| 2898 | | idempotent. (A sequence is idempotent if a single execution of the |
| 2899 | | entire sequence always yields a result that is not changed by a |
| 2900 | | reexecution of all, or part, of that sequence.) For example, a |
| 2901 | | sequence is non-idempotent if its result depends on a value that is |
| 2902 | | later modified in the same sequence. |
| 2903 | | </t> |
| 2904 | | <t> |
| 2905 | | A sequence that never has side effects is idempotent, by definition |
| 2906 | | (provided that no concurrent operations are being executed on the |
| 2907 | | same set of resources). |
| 2908 | | </t> |
| 2909 | | </section> |
| 2910 | | </section> |
| 2911 | | |
| 2912 | | <section title="OPTIONS" anchor="OPTIONS"> |
| 2913 | | <iref primary="true" item="OPTIONS method" x:for-anchor=""/> |
| 2914 | | <iref primary="true" item="Methods" subitem="OPTIONS" x:for-anchor=""/> |
| 2915 | | <t> |
| 2916 | | The OPTIONS method represents a request for information about the |
| 2917 | | communication options available on the request/response chain |
| 2918 | | identified by the Request-URI. This method allows the client to |
| 2919 | | determine the options and/or requirements associated with a resource, |
| 2920 | | or the capabilities of a server, without implying a resource action |
| 2921 | | or initiating a resource retrieval. |
| 2922 | | </t> |
| 2923 | | <t> |
| 2924 | | Responses to this method are not cacheable. |
| 2925 | | </t> |
| 2926 | | <t> |
| 2927 | | If the OPTIONS request includes an entity-body (as indicated by the |
| 2928 | | presence of Content-Length or Transfer-Encoding), then the media type |
| 2929 | | &MUST; be indicated by a Content-Type field. Although this |
| 2930 | | specification does not define any use for such a body, future |
| 2931 | | extensions to HTTP might use the OPTIONS body to make more detailed |
| 2932 | | queries on the server. A server that does not support such an |
| 2933 | | extension &MAY; discard the request body. |
| 2934 | | </t> |
| 2935 | | <t> |
| 2936 | | If the Request-URI is an asterisk ("*"), the OPTIONS request is |
| 2937 | | intended to apply to the server in general rather than to a specific |
| 2938 | | resource. Since a server's communication options typically depend on |
| 2939 | | the resource, the "*" request is only useful as a "ping" or "no-op" |
| 2940 | | type of method; it does nothing beyond allowing the client to test |
| 2941 | | the capabilities of the server. For example, this can be used to test |
| 2942 | | a proxy for HTTP/1.1 compliance (or lack thereof). |
| 2943 | | </t> |
| 2944 | | <t> |
| 2945 | | If the Request-URI is not an asterisk, the OPTIONS request applies |
| 2946 | | only to the options that are available when communicating with that |
| 2947 | | resource. |
| 2948 | | </t> |
| 2949 | | <t> |
| 2950 | | A 200 response &SHOULD; include any header fields that indicate |
| 2951 | | optional features implemented by the server and applicable to that |
| 2952 | | resource (e.g., Allow), possibly including extensions not defined by |
| 2953 | | this specification. The response body, if any, &SHOULD; also include |
| 2954 | | information about the communication options. The format for such a |
| 2955 | | body is not defined by this specification, but might be defined by |
| 2956 | | future extensions to HTTP. Content negotiation &MAY; be used to select |
| 2957 | | the appropriate response format. If no response body is included, the |
| 2958 | | response &MUST; include a Content-Length field with a field-value of |
| 2959 | | "0". |
| 2960 | | </t> |
| 2961 | | <t> |
| 2962 | | The Max-Forwards request-header field &MAY; be used to target a |
| 2963 | | specific proxy in the request chain. When a proxy receives an OPTIONS |
| 2964 | | request on an absoluteURI for which request forwarding is permitted, |
| 2965 | | the proxy &MUST; check for a Max-Forwards field. If the Max-Forwards |
| 2966 | | field-value is zero ("0"), the proxy &MUST-NOT; forward the message; |
| 2967 | | instead, the proxy &SHOULD; respond with its own communication options. |
| 2968 | | If the Max-Forwards field-value is an integer greater than zero, the |
| 2969 | | proxy &MUST; decrement the field-value when it forwards the request. If |
| 2970 | | no Max-Forwards field is present in the request, then the forwarded |
| 2971 | | request &MUST-NOT; include a Max-Forwards field. |
| 2972 | | </t> |
| 2973 | | </section> |
| 2974 | | |
| 2975 | | <section title="GET" anchor="GET"> |
| 2976 | | <iref primary="true" item="GET method" x:for-anchor=""/> |
| 2977 | | <iref primary="true" item="Methods" subitem="GET" x:for-anchor=""/> |
| 2978 | | <t> |
| 2979 | | The GET method means retrieve whatever information (in the form of an |
| 2980 | | entity) is identified by the Request-URI. If the Request-URI refers |
| 2981 | | to a data-producing process, it is the produced data which shall be |
| 2982 | | returned as the entity in the response and not the source text of the |
| 2983 | | process, unless that text happens to be the output of the process. |
| 2984 | | </t> |
| 2985 | | <t> |
| 2986 | | The semantics of the GET method change to a "conditional GET" if the |
| 2987 | | request message includes an If-Modified-Since, If-Unmodified-Since, |
| 2988 | | If-Match, If-None-Match, or If-Range header field. A conditional GET |
| 2989 | | method requests that the entity be transferred only under the |
| 2990 | | circumstances described by the conditional header field(s). The |
| 2991 | | conditional GET method is intended to reduce unnecessary network |
| 2992 | | usage by allowing cached entities to be refreshed without requiring |
| 2993 | | multiple requests or transferring data already held by the client. |
| 2994 | | </t> |
| 2995 | | <t> |
| 2996 | | The semantics of the GET method change to a "partial GET" if the |
| 2997 | | request message includes a Range header field. A partial GET requests |
| 2998 | | that only part of the entity be transferred, as described in <xref target="header.range"/>. |
| 2999 | | The partial GET method is intended to reduce unnecessary |
| 3000 | | network usage by allowing partially-retrieved entities to be |
| 3001 | | completed without transferring data already held by the client. |
| 3002 | | </t> |
| 3003 | | <t> |
| 3004 | | The response to a GET request is cacheable if and only if it meets |
| 3005 | | the requirements for HTTP caching described in <xref target="caching"/>. |
| 3006 | | </t> |
| 3007 | | <t> |
| 3008 | | See <xref target="encoding.sensitive.information.in.uris"/> for security considerations when used for forms. |
| 3009 | | </t> |
| 3010 | | </section> |
| 3011 | | |
| 3012 | | <section title="HEAD" anchor="HEAD"> |
| 3013 | | <iref primary="true" item="HEAD method" x:for-anchor=""/> |
| 3014 | | <iref primary="true" item="Methods" subitem="HEAD" x:for-anchor=""/> |
| 3015 | | <t> |
| 3016 | | The HEAD method is identical to GET except that the server &MUST-NOT; |
| 3017 | | return a message-body in the response. The metainformation contained |
| 3018 | | in the HTTP headers in response to a HEAD request &SHOULD; be identical |
| 3019 | | to the information sent in response to a GET request. This method can |
| 3020 | | be used for obtaining metainformation about the entity implied by the |
| 3021 | | request without transferring the entity-body itself. This method is |
| 3022 | | often used for testing hypertext links for validity, accessibility, |
| 3023 | | and recent modification. |
| 3024 | | </t> |
| 3025 | | <t> |
| 3026 | | The response to a HEAD request &MAY; be cacheable in the sense that the |
| 3027 | | information contained in the response &MAY; be used to update a |
| 3028 | | previously cached entity from that resource. If the new field values |
| 3029 | | indicate that the cached entity differs from the current entity (as |
| 3030 | | would be indicated by a change in Content-Length, Content-MD5, ETag |
| 3031 | | or Last-Modified), then the cache &MUST; treat the cache entry as |
| 3032 | | stale. |
| 3033 | | </t> |
| 3034 | | </section> |
| 3035 | | |
| 3036 | | <section title="POST" anchor="POST"> |
| 3037 | | <iref primary="true" item="POST method" x:for-anchor=""/> |
| 3038 | | <iref primary="true" item="Methods" subitem="POST" x:for-anchor=""/> |
| 3039 | | <t> |
| 3040 | | The POST method is used to request that the origin server accept the |
| 3041 | | entity enclosed in the request as a new subordinate of the resource |
| 3042 | | identified by the Request-URI in the Request-Line. POST is designed |
| 3043 | | to allow a uniform method to cover the following functions: |
| 3044 | | <list style="symbols"> |
| 3045 | | <t> |
| 3046 | | Annotation of existing resources; |
| 3047 | | </t> |
| 3048 | | <t> |
| 3049 | | Posting a message to a bulletin board, newsgroup, mailing list, |
| 3050 | | or similar group of articles; |
| 3051 | | </t> |
| 3052 | | <t> |
| 3053 | | Providing a block of data, such as the result of submitting a |
| 3054 | | form, to a data-handling process; |
| 3055 | | </t> |
| 3056 | | <t> |
| 3057 | | Extending a database through an append operation. |
| 3058 | | </t> |
| 3059 | | </list> |
| 3060 | | </t> |
| 3061 | | <t> |
| 3062 | | The actual function performed by the POST method is determined by the |
| 3063 | | server and is usually dependent on the Request-URI. The posted entity |
| 3064 | | is subordinate to that URI in the same way that a file is subordinate |
| 3065 | | to a directory containing it, a news article is subordinate to a |
| 3066 | | newsgroup to which it is posted, or a record is subordinate to a |
| 3067 | | database. |
| 3068 | | </t> |
| 3069 | | <t> |
| 3070 | | The action performed by the POST method might not result in a |
| 3071 | | resource that can be identified by a URI. In this case, either 200 |
| 3072 | | (OK) or 204 (No Content) is the appropriate response status, |
| 3073 | | depending on whether or not the response includes an entity that |
| 3074 | | describes the result. |
| 3075 | | </t> |
| 3076 | | <t> |
| 3077 | | If a resource has been created on the origin server, the response |
| 3078 | | &SHOULD; be 201 (Created) and contain an entity which describes the |
| 3079 | | status of the request and refers to the new resource, and a Location |
| 3080 | | header (see <xref target="header.location"/>). |
| 3081 | | </t> |
| 3082 | | <t> |
| 3083 | | Responses to this method are not cacheable, unless the response |
| 3084 | | includes appropriate Cache-Control or Expires header fields. However, |
| 3085 | | the 303 (See Other) response can be used to direct the user agent to |
| 3086 | | retrieve a cacheable resource. |
| 3087 | | </t> |
| 3088 | | <t> |
| 3089 | | POST requests &MUST; obey the message transmission requirements set out |
| 3090 | | in <xref target="message.transmission.requirements"/>. |
| 3091 | | </t> |
| 3092 | | <t> |
| 3093 | | See <xref target="encoding.sensitive.information.in.uris"/> for security considerations. |
| 3094 | | </t> |
| 3095 | | </section> |
| 3096 | | |
| 3097 | | <section title="PUT" anchor="PUT"> |
| 3098 | | <iref primary="true" item="PUT method" x:for-anchor=""/> |
| 3099 | | <iref primary="true" item="Methods" subitem="PUT" x:for-anchor=""/> |
| 3100 | | <t> |
| 3101 | | The PUT method requests that the enclosed entity be stored under the |
| 3102 | | supplied Request-URI. If the Request-URI refers to an already |
| 3103 | | existing resource, the enclosed entity &SHOULD; be considered as a |
| 3104 | | modified version of the one residing on the origin server. If the |
| 3105 | | Request-URI does not point to an existing resource, and that URI is |
| 3106 | | capable of being defined as a new resource by the requesting user |
| 3107 | | agent, the origin server can create the resource with that URI. If a |
| 3108 | | new resource is created, the origin server &MUST; inform the user agent |
| 3109 | | via the 201 (Created) response. If an existing resource is modified, |
| 3110 | | either the 200 (OK) or 204 (No Content) response codes &SHOULD; be sent |
| 3111 | | to indicate successful completion of the request. If the resource |
| 3112 | | could not be created or modified with the Request-URI, an appropriate |
| 3113 | | error response &SHOULD; be given that reflects the nature of the |
| 3114 | | problem. The recipient of the entity &MUST-NOT; ignore any Content-* |
| 3115 | | (e.g. Content-Range) headers that it does not understand or implement |
| 3116 | | and &MUST; return a 501 (Not Implemented) response in such cases. |
| 3117 | | </t> |
| 3118 | | <t> |
| 3119 | | If the request passes through a cache and the Request-URI identifies |
| 3120 | | one or more currently cached entities, those entries &SHOULD; be |
| 3121 | | treated as stale. Responses to this method are not cacheable. |
| 3122 | | </t> |
| 3123 | | <t> |
| 3124 | | The fundamental difference between the POST and PUT requests is |
| 3125 | | reflected in the different meaning of the Request-URI. The URI in a |
| 3126 | | POST request identifies the resource that will handle the enclosed |
| 3127 | | entity. That resource might be a data-accepting process, a gateway to |
| 3128 | | some other protocol, or a separate entity that accepts annotations. |
| 3129 | | In contrast, the URI in a PUT request identifies the entity enclosed |
| 3130 | | with the request -- the user agent knows what URI is intended and the |
| 3131 | | server &MUST-NOT; attempt to apply the request to some other resource. |
| 3132 | | If the server desires that the request be applied to a different URI, |
| 3133 | | it &MUST; send a 301 (Moved Permanently) response; the user agent &MAY; |
| 3134 | | then make its own decision regarding whether or not to redirect the |
| 3135 | | request. |
| 3136 | | </t> |
| 3137 | | <t> |
| 3138 | | A single resource &MAY; be identified by many different URIs. For |
| 3139 | | example, an article might have a URI for identifying "the current |
| 3140 | | version" which is separate from the URI identifying each particular |
| 3141 | | version. In this case, a PUT request on a general URI might result in |
| 3142 | | several other URIs being defined by the origin server. |
| 3143 | | </t> |
| 3144 | | <t> |
| 3145 | | HTTP/1.1 does not define how a PUT method affects the state of an |
| 3146 | | origin server. |
| 3147 | | </t> |
| 3148 | | <t> |
| 3149 | | PUT requests &MUST; obey the message transmission requirements set out |
| 3150 | | in <xref target="message.transmission.requirements"/>. |
| 3151 | | </t> |
| 3152 | | <t> |
| 3153 | | Unless otherwise specified for a particular entity-header, the |
| 3154 | | entity-headers in the PUT request &SHOULD; be applied to the resource |
| 3155 | | created or modified by the PUT. |
| 3156 | | </t> |
| 3157 | | </section> |
| 3158 | | |
| 3159 | | <section title="DELETE" anchor="DELETE"> |
| 3160 | | <iref primary="true" item="DELETE method" x:for-anchor=""/> |
| 3161 | | <iref primary="true" item="Methods" subitem="DELETE" x:for-anchor=""/> |
| 3162 | | <t> |
| 3163 | | The DELETE method requests that the origin server delete the resource |
| 3164 | | identified by the Request-URI. This method &MAY; be overridden by human |
| 3165 | | intervention (or other means) on the origin server. The client cannot |
| 3166 | | be guaranteed that the operation has been carried out, even if the |
| 3167 | | status code returned from the origin server indicates that the action |
| 3168 | | has been completed successfully. However, the server &SHOULD-NOT; |
| 3169 | | indicate success unless, at the time the response is given, it |
| 3170 | | intends to delete the resource or move it to an inaccessible |
| 3171 | | location. |
| 3172 | | </t> |
| 3173 | | <t> |
| 3174 | | A successful response &SHOULD; be 200 (OK) if the response includes an |
| 3175 | | entity describing the status, 202 (Accepted) if the action has not |
| 3176 | | yet been enacted, or 204 (No Content) if the action has been enacted |
| 3177 | | but the response does not include an entity. |
| 3178 | | </t> |
| 3179 | | <t> |
| 3180 | | If the request passes through a cache and the Request-URI identifies |
| 3181 | | one or more currently cached entities, those entries &SHOULD; be |
| 3182 | | treated as stale. Responses to this method are not cacheable. |
| 3183 | | </t> |
| 3184 | | </section> |
| 3185 | | |
| 3186 | | <section title="TRACE" anchor="TRACE"> |
| 3187 | | <iref primary="true" item="TRACE method" x:for-anchor=""/> |
| 3188 | | <iref primary="true" item="Methods" subitem="TRACE" x:for-anchor=""/> |
| 3189 | | <t> |
| 3190 | | The TRACE method is used to invoke a remote, application-layer loop-back |
| 3191 | | of the request message. The final recipient of the request |
| 3192 | | &SHOULD; reflect the message received back to the client as the |
| 3193 | | entity-body of a 200 (OK) response. The final recipient is either the |
| 3194 | | origin server or the first proxy or gateway to receive a Max-Forwards |
| 3195 | | value of zero (0) in the request (see <xref target="header.max-forwards"/>). A TRACE request |
| 3196 | | &MUST-NOT; include an entity. |
| 3197 | | </t> |
| 3198 | | <t> |
| 3199 | | TRACE allows the client to see what is being received at the other |
| 3200 | | end of the request chain and use that data for testing or diagnostic |
| 3201 | | information. The value of the Via header field (<xref target="header.via"/>) is of |
| 3202 | | particular interest, since it acts as a trace of the request chain. |
| 3203 | | Use of the Max-Forwards header field allows the client to limit the |
| 3204 | | length of the request chain, which is useful for testing a chain of |
| 3205 | | proxies forwarding messages in an infinite loop. |
| 3206 | | </t> |
| 3207 | | <t> |
| 3208 | | If the request is valid, the response &SHOULD; contain the entire |
| 3209 | | request message in the entity-body, with a Content-Type of |
| 3210 | | "message/http". Responses to this method &MUST-NOT; be cached. |
| 3211 | | </t> |
| 3212 | | </section> |
| 3213 | | |
| 3214 | | <section title="CONNECT" anchor="CONNECT"> |
| 3215 | | <iref primary="true" item="CONNECT method" x:for-anchor=""/> |
| 3216 | | <iref primary="true" item="Methods" subitem="CONNECT" x:for-anchor=""/> |
| 3217 | | <t> |
| 3218 | | This specification reserves the method name CONNECT for use with a |
| 3219 | | proxy that can dynamically switch to being a tunnel (e.g. SSL |
| 3220 | | tunneling <xref target="Luo1998"/>). |
| 3221 | | </t> |
| 3222 | | </section> |
| 3223 | | </section> |
| 3224 | | |
| 3225 | | |
| 3226 | | <section title="Status Code Definitions" anchor="status.codes"> |
| 3227 | | <t> |
| 3228 | | Each Status-Code is described below, including a description of which |
| 3229 | | method(s) it can follow and any metainformation required in the |
| 3230 | | response. |
| 3231 | | </t> |
| 3232 | | |
| 3233 | | <section title="Informational 1xx" anchor="status.1xx"> |
| 3234 | | <t> |
| 3235 | | This class of status code indicates a provisional response, |
| 3236 | | consisting only of the Status-Line and optional headers, and is |
| 3237 | | terminated by an empty line. There are no required headers for this |
| 3238 | | class of status code. Since HTTP/1.0 did not define any 1xx status |
| 3239 | | codes, servers &MUST-NOT; send a 1xx response to an HTTP/1.0 client |
| 3240 | | except under experimental conditions. |
| 3241 | | </t> |
| 3242 | | <t> |
| 3243 | | A client &MUST; be prepared to accept one or more 1xx status responses |
| 3244 | | prior to a regular response, even if the client does not expect a 100 |
| 3245 | | (Continue) status message. Unexpected 1xx status responses &MAY; be |
| 3246 | | ignored by a user agent. |
| 3247 | | </t> |
| 3248 | | <t> |
| 3249 | | Proxies &MUST; forward 1xx responses, unless the connection between the |
| 3250 | | proxy and its client has been closed, or unless the proxy itself |
| 3251 | | requested the generation of the 1xx response. (For example, if a |
| 3252 | | proxy adds a "Expect: 100-continue" field when it forwards a request, |
| 3253 | | then it need not forward the corresponding 100 (Continue) |
| 3254 | | response(s).) |
| 3255 | | </t> |
| 3256 | | |
| 3257 | | <section title="100 Continue" anchor="status.100"> |
| 3258 | | <iref primary="true" item="100 Continue (status code)" x:for-anchor=""/> |
| 3259 | | <iref primary="true" item="Status Codes" subitem="100 Continue" x:for-anchor=""/> |
| 3260 | | <t> |
| 3261 | | The client &SHOULD; continue with its request. This interim response is |
| 3262 | | used to inform the client that the initial part of the request has |
| 3263 | | been received and has not yet been rejected by the server. The client |
| 3264 | | &SHOULD; continue by sending the remainder of the request or, if the |
| 3265 | | request has already been completed, ignore this response. The server |
| 3266 | | &MUST; send a final response after the request has been completed. See |
| 3267 | | <xref target="use.of.the.100.status"/> for detailed discussion of the use and handling of this |
| 3268 | | status code. |
| 3269 | | </t> |
| 3270 | | </section> |
| 3271 | | |
| 3272 | | <section title="101 Switching Protocols" anchor="status.101"> |
| 3273 | | <iref primary="true" item="101 Switching Protocols (status code)" x:for-anchor=""/> |
| 3274 | | <iref primary="true" item="Status Codes" subitem="101 Switching Protocols" x:for-anchor=""/> |
| 3275 | | <t> |
| 3276 | | The server understands and is willing to comply with the client's |
| 3277 | | request, via the Upgrade message header field (<xref target="header.upgrade"/>), for a |
| 3278 | | change in the application protocol being used on this connection. The |
| 3279 | | server will switch protocols to those defined by the response's |
| 3280 | | Upgrade header field immediately after the empty line which |
| 3281 | | terminates the 101 response. |
| 3282 | | </t> |
| 3283 | | <t> |
| 3284 | | The protocol &SHOULD; be switched only when it is advantageous to do |
| 3285 | | so. For example, switching to a newer version of HTTP is advantageous |
| 3286 | | over older versions, and switching to a real-time, synchronous |
| 3287 | | protocol might be advantageous when delivering resources that use |
| 3288 | | such features. |
| 3289 | | </t> |
| 3290 | | </section> |
| 3291 | | </section> |
| 3292 | | |
| 3293 | | <section title="Successful 2xx" anchor="status.2xx"> |
| 3294 | | <t> |
| 3295 | | This class of status code indicates that the client's request was |
| 3296 | | successfully received, understood, and accepted. |
| 3297 | | </t> |
| 3298 | | |
| 3299 | | <section title="200 OK" anchor="status.200"> |
| 3300 | | <iref primary="true" item="200 OK (status code)" x:for-anchor=""/> |
| 3301 | | <iref primary="true" item="Status Codes" subitem="200 OK" x:for-anchor=""/> |
| 3302 | | <t> |
| 3303 | | The request has succeeded. The information returned with the response |
| 3304 | | is dependent on the method used in the request, for example: |
| 3305 | | <list style="hanging"> |
| 3306 | | <t hangText="GET"> |
| 3307 | | an entity corresponding to the requested resource is sent in |
| 3308 | | the response; |
| 3309 | | </t> |
| 3310 | | <t hangText="HEAD"> |
| 3311 | | the entity-header fields corresponding to the requested |
| 3312 | | resource are sent in the response without any message-body; |
| 3313 | | </t> |
| 3314 | | <t hangText="POST"> |
| 3315 | | an entity describing or containing the result of the action; |
| 3316 | | </t> |
| 3317 | | <t hangText="TRACE"> |
| 3318 | | an entity containing the request message as received by the |
| 3319 | | end server. |
| 3320 | | </t> |
| 3321 | | </list> |
| 3322 | | </t> |
| 3323 | | </section> |
| 3324 | | |
| 3325 | | <section title="201 Created" anchor="status.201"> |
| 3326 | | <iref primary="true" item="201 Created (status code)" x:for-anchor=""/> |
| 3327 | | <iref primary="true" item="Status Codes" subitem="201 Created" x:for-anchor=""/> |
| 3328 | | <t> |
| 3329 | | The request has been fulfilled and resulted in a new resource being |
| 3330 | | created. The newly created resource can be referenced by the URI(s) |
| 3331 | | returned in the entity of the response, with the most specific URI |
| 3332 | | for the resource given by a Location header field. The response |
| 3333 | | &SHOULD; include an entity containing a list of resource |
| 3334 | | characteristics and location(s) from which the user or user agent can |
| 3335 | | choose the one most appropriate. The entity format is specified by |
| 3336 | | the media type given in the Content-Type header field. The origin |
| 3337 | | server &MUST; create the resource before returning the 201 status code. |
| 3338 | | If the action cannot be carried out immediately, the server &SHOULD; |
| 3339 | | respond with 202 (Accepted) response instead. |
| 3340 | | </t> |
| 3341 | | <t> |
| 3342 | | A 201 response &MAY; contain an ETag response header field indicating |
| 3343 | | the current value of the entity tag for the requested variant just |
| 3344 | | created, see <xref target="header.etag"/>. |
| 3345 | | </t> |
| 3346 | | </section> |
| 3347 | | |
| 3348 | | <section title="202 Accepted" anchor="status.202"> |
| 3349 | | <iref primary="true" item="202 Accepted (status code)" x:for-anchor=""/> |
| 3350 | | <iref primary="true" item="Status Codes" subitem="202 Accepted" x:for-anchor=""/> |
| 3351 | | <t> |
| 3352 | | The request has been accepted for processing, but the processing has |
| 3353 | | not been completed. The request might or might not eventually be |
| 3354 | | acted upon, as it might be disallowed when processing actually takes |
| 3355 | | place. There is no facility for re-sending a status code from an |
| 3356 | | asynchronous operation such as this. |
| 3357 | | </t> |
| 3358 | | <t> |
| 3359 | | The 202 response is intentionally non-committal. Its purpose is to |
| 3360 | | allow a server to accept a request for some other process (perhaps a |
| 3361 | | batch-oriented process that is only run once per day) without |
| 3362 | | requiring that the user agent's connection to the server persist |
| 3363 | | until the process is completed. The entity returned with this |
| 3364 | | response &SHOULD; include an indication of the request's current status |
| 3365 | | and either a pointer to a status monitor or some estimate of when the |
| 3366 | | user can expect the request to be fulfilled. |
| 3367 | | </t> |
| 3368 | | </section> |
| 3369 | | |
| 3370 | | <section title="203 Non-Authoritative Information" anchor="status.203"> |
| 3371 | | <iref primary="true" item="203 Non-Authoritative Information (status code)" x:for-anchor=""/> |
| 3372 | | <iref primary="true" item="Status Codes" subitem="203 Non-Authoritative Information" x:for-anchor=""/> |
| 3373 | | <t> |
| 3374 | | The returned metainformation in the entity-header is not the |
| 3375 | | definitive set as available from the origin server, but is gathered |
| 3376 | | from a local or a third-party copy. The set presented &MAY; be a subset |
| 3377 | | or superset of the original version. For example, including local |
| 3378 | | annotation information about the resource might result in a superset |
| 3379 | | of the metainformation known by the origin server. Use of this |
| 3380 | | response code is not required and is only appropriate when the |
| 3381 | | response would otherwise be 200 (OK). |
| 3382 | | </t> |
| 3383 | | </section> |
| 3384 | | |
| 3385 | | <section title="204 No Content" anchor="status.204"> |
| 3386 | | <iref primary="true" item="204 No Content (status code)" x:for-anchor=""/> |
| 3387 | | <iref primary="true" item="Status Codes" subitem="204 No Content" x:for-anchor=""/> |
| 3388 | | <t> |
| 3389 | | The server has fulfilled the request but does not need to return an |
| 3390 | | entity-body, and might want to return updated metainformation. The |
| 3391 | | response &MAY; include new or updated metainformation in the form of |
| 3392 | | entity-headers, which if present &SHOULD; be associated with the |
| 3393 | | requested variant. |
| 3394 | | </t> |
| 3395 | | <t> |
| 3396 | | If the client is a user agent, it &SHOULD-NOT; change its document view |
| 3397 | | from that which caused the request to be sent. This response is |
| 3398 | | primarily intended to allow input for actions to take place without |
| 3399 | | causing a change to the user agent's active document view, although |
| 3400 | | any new or updated metainformation &SHOULD; be applied to the document |
| 3401 | | currently in the user agent's active view. |
| 3402 | | </t> |
| 3403 | | <t> |
| 3404 | | The 204 response &MUST-NOT; include a message-body, and thus is always |
| 3405 | | terminated by the first empty line after the header fields. |
| 3406 | | </t> |
| 3407 | | </section> |
| 3408 | | |
| 3409 | | <section title="205 Reset Content" anchor="status.205"> |
| 3410 | | <iref primary="true" item="205 Reset Content (status code)" x:for-anchor=""/> |
| 3411 | | <iref primary="true" item="Status Codes" subitem="205 Reset Content" x:for-anchor=""/> |
| 3412 | | <t> |
| 3413 | | The server has fulfilled the request and the user agent &SHOULD; reset |
| 3414 | | the document view which caused the request to be sent. This response |
| 3415 | | is primarily intended to allow input for actions to take place via |
| 3416 | | user input, followed by a clearing of the form in which the input is |
| 3417 | | given so that the user can easily initiate another input action. The |
| 3418 | | response &MUST-NOT; include an entity. |
| 3419 | | </t> |
| 3420 | | </section> |
| 3421 | | |
| 3422 | | <section title="206 Partial Content" anchor="status.206"> |
| 3423 | | <iref primary="true" item="206 Partial Content (status code)" x:for-anchor=""/> |
| 3424 | | <iref primary="true" item="Status Codes" subitem="206 Partial Content" x:for-anchor=""/> |
| 3425 | | <t> |
| 3426 | | The server has fulfilled the partial GET request for the resource. |
| 3427 | | The request &MUST; have included a Range header field (<xref target="header.range"/>) |
| 3428 | | indicating the desired range, and &MAY; have included an If-Range |
| 3429 | | header field (<xref target="header.if-range"/>) to make the request conditional. |
| 3430 | | </t> |
| 3431 | | <t> |
| 3432 | | The response &MUST; include the following header fields: |
| 3433 | | <list style="symbols"> |
| 3434 | | <t> |
| 3435 | | Either a Content-Range header field (<xref target="header.content-range"/>) indicating |
| 3436 | | the range included with this response, or a multipart/byteranges |
| 3437 | | Content-Type including Content-Range fields for each part. If a |
| 3438 | | Content-Length header field is present in the response, its |
| 3439 | | value &MUST; match the actual number of OCTETs transmitted in the |
| 3440 | | message-body. |
| 3441 | | </t> |
| 3442 | | <t> |
| 3443 | | Date |
| 3444 | | </t> |
| 3445 | | <t> |
| 3446 | | ETag and/or Content-Location, if the header would have been sent |
| 3447 | | in a 200 response to the same request |
| 3448 | | </t> |
| 3449 | | <t> |
| 3450 | | Expires, Cache-Control, and/or Vary, if the field-value might |
| 3451 | | differ from that sent in any previous response for the same |
| 3452 | | variant |
| 3453 | | </t> |
| 3454 | | </list> |
| 3455 | | </t> |
| 3456 | | <t> |
| 3457 | | If the 206 response is the result of an If-Range request that used a |
| 3458 | | strong cache validator (see <xref target="weak.and.strong.validators"/>), the response &SHOULD-NOT; |
| 3459 | | include other entity-headers. If the response is the result of an |
| 3460 | | If-Range request that used a weak validator, the response &MUST-NOT; |
| 3461 | | include other entity-headers; this prevents inconsistencies between |
| 3462 | | cached entity-bodies and updated headers. Otherwise, the response |
| 3463 | | &MUST; include all of the entity-headers that would have been returned |
| 3464 | | with a 200 (OK) response to the same request. |
| 3465 | | </t> |
| 3466 | | <t> |
| 3467 | | A cache &MUST-NOT; combine a 206 response with other previously cached |
| 3468 | | content if the ETag or Last-Modified headers do not match exactly, |
| 3469 | | see <xref target="combining.byte.ranges" format="counter"/>. |
| 3470 | | </t> |
| 3471 | | <t> |
| 3472 | | A cache that does not support the Range and Content-Range headers |
| 3473 | | &MUST-NOT; cache 206 (Partial) responses. |
| 3474 | | </t> |
| 3475 | | </section> |
| 3476 | | </section> |
| 3477 | | |
| 3478 | | <section title="Redirection 3xx" anchor="status.3xx"> |
| 3479 | | <t> |
| 3480 | | This class of status code indicates that further action needs to be |
| 3481 | | taken by the user agent in order to fulfill the request. The action |
| 3482 | | required &MAY; be carried out by the user agent without interaction |
| 3483 | | with the user if and only if the method used in the second request is |
| 3484 | | GET or HEAD. A client &SHOULD; detect infinite redirection loops, since |
| 3485 | | such loops generate network traffic for each redirection. |
| 3486 | | <list><t> |
| 3487 | | <x:h>Note:</x:h> previous versions of this specification recommended a |
| 3488 | | maximum of five redirections. Content developers should be aware |
| 3489 | | that there might be clients that implement such a fixed |
| 3490 | | limitation. |
| 3491 | | </t></list> |
| 3492 | | </t> |
| 3493 | | |
| 3494 | | <section title="300 Multiple Choices" anchor="status.300"> |
| 3495 | | <iref primary="true" item="300 Multiple Choices (status code)" x:for-anchor=""/> |
| 3496 | | <iref primary="true" item="Status Codes" subitem="300 Multiple Choices" x:for-anchor=""/> |
| 3497 | | <t> |
| 3498 | | The requested resource corresponds to any one of a set of |
| 3499 | | representations, each with its own specific location, and agent-driven |
| 3500 | | negotiation information (<xref target="content.negotiation"/>) is being provided so that |
| 3501 | | the user (or user agent) can select a preferred representation and |
| 3502 | | redirect its request to that location. |
| 3503 | | </t> |
| 3504 | | <t> |
| 3505 | | Unless it was a HEAD request, the response &SHOULD; include an entity |
| 3506 | | containing a list of resource characteristics and location(s) from |
| 3507 | | which the user or user agent can choose the one most appropriate. The |
| 3508 | | entity format is specified by the media type given in the Content-Type |
| 3509 | | header field. Depending upon the format and the capabilities of |
| 3510 | | the user agent, selection of the most appropriate choice &MAY; be |
| 3511 | | performed automatically. However, this specification does not define |
| 3512 | | any standard for such automatic selection. |
| 3513 | | </t> |
| 3514 | | <t> |
| 3515 | | If the server has a preferred choice of representation, it &SHOULD; |
| 3516 | | include the specific URI for that representation in the Location |
| 3517 | | field; user agents &MAY; use the Location field value for automatic |
| 3518 | | redirection. This response is cacheable unless indicated otherwise. |
| 3519 | | </t> |
| 3520 | | </section> |
| 3521 | | |
| 3522 | | <section title="301 Moved Permanently" anchor="status.301"> |
| 3523 | | <iref primary="true" item="301 Moved Permanently (status code)" x:for-anchor=""/> |
| 3524 | | <iref primary="true" item="Status Codes" subitem="301 Moved Permanently" x:for-anchor=""/> |
| 3525 | | <t> |
| 3526 | | The requested resource has been assigned a new permanent URI and any |
| 3527 | | future references to this resource &SHOULD; use one of the returned |
| 3528 | | URIs. Clients with link editing capabilities ought to automatically |
| 3529 | | re-link references to the Request-URI to one or more of the new |
| 3530 | | references returned by the server, where possible. This response is |
| 3531 | | cacheable unless indicated otherwise. |
| 3532 | | </t> |
| 3533 | | <t> |
| 3534 | | The new permanent URI &SHOULD; be given by the Location field in the |
| 3535 | | response. Unless the request method was HEAD, the entity of the |
| 3536 | | response &SHOULD; contain a short hypertext note with a hyperlink to |
| 3537 | | the new URI(s). |
| 3538 | | </t> |
| 3539 | | <t> |
| 3540 | | If the 301 status code is received in response to a request other |
| 3541 | | than GET or HEAD, the user agent &MUST-NOT; automatically redirect the |
| 3542 | | request unless it can be confirmed by the user, since this might |
| 3543 | | change the conditions under which the request was issued. |
| 3544 | | <list><t> |
| 3545 | | <x:h>Note:</x:h> When automatically redirecting a POST request after |
| 3546 | | receiving a 301 status code, some existing HTTP/1.0 user agents |
| 3547 | | will erroneously change it into a GET request. |
| 3548 | | </t></list> |
| 3549 | | </t> |
| 3550 | | </section> |
| 3551 | | |
| 3552 | | <section title="302 Found" anchor="status.302"> |
| 3553 | | <iref primary="true" item="302 Found (status code)" x:for-anchor=""/> |
| 3554 | | <iref primary="true" item="Status Codes" subitem="302 Found" x:for-anchor=""/> |
| 3555 | | <t> |
| 3556 | | The requested resource resides temporarily under a different URI. |
| 3557 | | Since the redirection might be altered on occasion, the client &SHOULD; |
| 3558 | | continue to use the Request-URI for future requests. This response |
| 3559 | | is only cacheable if indicated by a Cache-Control or Expires header |
| 3560 | | field. |
| 3561 | | </t> |
| 3562 | | <t> |
| 3563 | | The temporary URI &SHOULD; be given by the Location field in the |
| 3564 | | response. Unless the request method was HEAD, the entity of the |
| 3565 | | response &SHOULD; contain a short hypertext note with a hyperlink to |
| 3566 | | the new URI(s). |
| 3567 | | </t> |
| 3568 | | <t> |
| 3569 | | If the 302 status code is received in response to a request other |
| 3570 | | than GET or HEAD, the user agent &MUST-NOT; automatically redirect the |
| 3571 | | request unless it can be confirmed by the user, since this might |
| 3572 | | change the conditions under which the request was issued. |
| 3573 | | <list><t> |
| 3574 | | <x:h>Note:</x:h> RFC 1945 and RFC 2068 specify that the client is not allowed |
| 3575 | | to change the method on the redirected request. However, most |
| 3576 | | existing user agent implementations treat 302 as if it were a 303 |
| 3577 | | response, performing a GET on the Location field-value regardless |
| 3578 | | of the original request method. The status codes 303 and 307 have |
| 3579 | | been added for servers that wish to make unambiguously clear which |
| 3580 | | kind of reaction is expected of the client. |
| 3581 | | </t></list> |
| 3582 | | </t> |
| 3583 | | </section> |
| 3584 | | |
| 3585 | | <section title="303 See Other" anchor="status.303"> |
| 3586 | | <iref primary="true" item="303 See Other (status code)" x:for-anchor=""/> |
| 3587 | | <iref primary="true" item="Status Codes" subitem="303 See Other" x:for-anchor=""/> |
| 3588 | | <t> |
| 3589 | | The response to the request can be found under a different URI and |
| 3590 | | &SHOULD; be retrieved using a GET method on that resource. This method |
| 3591 | | exists primarily to allow the output of a POST-activated script to |
| 3592 | | redirect the user agent to a selected resource. The new URI is not a |
| 3593 | | substitute reference for the originally requested resource. The 303 |
| 3594 | | response &MUST-NOT; be cached, but the response to the second |
| 3595 | | (redirected) request might be cacheable. |
| 3596 | | </t> |
| 3597 | | <t> |
| 3598 | | The different URI &SHOULD; be given by the Location field in the |
| 3599 | | response. Unless the request method was HEAD, the entity of the |
| 3600 | | response &SHOULD; contain a short hypertext note with a hyperlink to |
| 3601 | | the new URI(s). |
| 3602 | | <list><t> |
| 3603 | | <x:h>Note:</x:h> Many pre-HTTP/1.1 user agents do not understand the 303 |
| 3604 | | status. When interoperability with such clients is a concern, the |
| 3605 | | 302 status code may be used instead, since most user agents react |
| 3606 | | to a 302 response as described here for 303. |
| 3607 | | </t></list> |
| 3608 | | </t> |
| 3609 | | </section> |
| 3610 | | |
| 3611 | | <section title="304 Not Modified" anchor="status.304"> |
| 3612 | | <iref primary="true" item="304 Not Modified (status code)" x:for-anchor=""/> |
| 3613 | | <iref primary="true" item="Status Codes" subitem="304 Not Modified" x:for-anchor=""/> |
| 3614 | | <t> |
| 3615 | | If the client has performed a conditional GET request and access is |
| 3616 | | allowed, but the document has not been modified, the server &SHOULD; |
| 3617 | | respond with this status code. The 304 response &MUST-NOT; contain a |
| 3618 | | message-body, and thus is always terminated by the first empty line |
| 3619 | | after the header fields. |
| 3620 | | </t> |
| 3621 | | <t> |
| 3622 | | The response &MUST; include the following header fields: |
| 3623 | | <list style="symbols"> |
| 3624 | | <t>Date, unless its omission is required by <xref target="clockless.origin.server.operation"/></t> |
| 3625 | | </list> |
| 3626 | | </t> |
| 3627 | | <t> |
| 3628 | | If a clockless origin server obeys these rules, and proxies and |
| 3629 | | clients add their own Date to any response received without one (as |
| 3630 | | already specified by [RFC 2068], section <xref target="RFC2068" x:sec="14.19" x:fmt="number"/>), caches will operate |
| 3631 | | correctly. |
| 3632 | | <list style="symbols"> |
| 3633 | | <t>ETag and/or Content-Location, if the header would have been sent |
| 3634 | | in a 200 response to the same request</t> |
| 3635 | | <t>Expires, Cache-Control, and/or Vary, if the field-value might |
| 3636 | | differ from that sent in any previous response for the same |
| 3637 | | variant</t> |
| 3638 | | </list> |
| 3639 | | </t> |
| 3640 | | <t> |
| 3641 | | If the conditional GET used a strong cache validator (see <xref target="weak.and.strong.validators"/>), |
| 3642 | | the response &SHOULD-NOT; include other entity-headers. |
| 3643 | | Otherwise (i.e., the conditional GET used a weak validator), the |
| 3644 | | response &MUST-NOT; include other entity-headers; this prevents |
| 3645 | | inconsistencies between cached entity-bodies and updated headers. |
| 3646 | | </t> |
| 3647 | | <t> |
| 3648 | | If a 304 response indicates an entity not currently cached, then the |
| 3649 | | cache &MUST; disregard the response and repeat the request without the |
| 3650 | | conditional. |
| 3651 | | </t> |
| 3652 | | <t> |
| 3653 | | If a cache uses a received 304 response to update a cache entry, the |
| 3654 | | cache &MUST; update the entry to reflect any new field values given in |
| 3655 | | the response. |
| 3656 | | </t> |
| 3657 | | </section> |
| 3658 | | |
| 3659 | | <section title="305 Use Proxy" anchor="status.305"> |
| 3660 | | <iref primary="true" item="305 Use Proxy (status code)" x:for-anchor=""/> |
| 3661 | | <iref primary="true" item="Status Codes" subitem="305 Use Proxy" x:for-anchor=""/> |
| 3662 | | <t> |
| 3663 | | The requested resource &MUST; be accessed through the proxy given by |
| 3664 | | the Location field. The Location field gives the URI of the proxy. |
| 3665 | | The recipient is expected to repeat this single request via the |
| 3666 | | proxy. 305 responses &MUST; only be generated by origin servers. |
| 3667 | | <list><t> |
| 3668 | | <x:h>Note:</x:h> RFC 2068 was not clear that 305 was intended to redirect a |
| 3669 | | single request, and to be generated by origin servers only. Not |
| 3670 | | observing these limitations has significant security consequences. |
| 3671 | | </t></list> |
| 3672 | | </t> |
| 3673 | | </section> |
| 3674 | | |
| 3675 | | <section title="306 (Unused)" anchor="status.306"> |
| 3676 | | <iref primary="true" item="306 (Unused) (status code)" x:for-anchor=""/> |
| 3677 | | <iref primary="true" item="Status Codes" subitem="306 (Unused)" x:for-anchor=""/> |
| 3678 | | <t> |
| 3679 | | The 306 status code was used in a previous version of the |
| 3680 | | specification, is no longer used, and the code is reserved. |
| 3681 | | </t> |
| 3682 | | </section> |
| 3683 | | |
| 3684 | | <section title="307 Temporary Redirect" anchor="status.307"> |
| 3685 | | <iref primary="true" item="307 Temporary Redirect (status code)" x:for-anchor=""/> |
| 3686 | | <iref primary="true" item="Status Codes" subitem="307 Temporary Redirect" x:for-anchor=""/> |
| 3687 | | <t> |
| 3688 | | The requested resource resides temporarily under a different URI. |
| 3689 | | Since the redirection &MAY; be altered on occasion, the client &SHOULD; |
| 3690 | | continue to use the Request-URI for future requests. This response |
| 3691 | | is only cacheable if indicated by a Cache-Control or Expires header |
| 3692 | | field. |
| 3693 | | </t> |
| 3694 | | <t> |
| 3695 | | The temporary URI &SHOULD; be given by the Location field in the |
| 3696 | | response. Unless the request method was HEAD, the entity of the |
| 3697 | | response &SHOULD; contain a short hypertext note with a hyperlink to |
| 3698 | | the new URI(s) , since many pre-HTTP/1.1 user agents do not |
| 3699 | | understand the 307 status. Therefore, the note &SHOULD; contain the |
| 3700 | | information necessary for a user to repeat the original request on |
| 3701 | | the new URI. |
| 3702 | | </t> |
| 3703 | | <t> |
| 3704 | | If the 307 status code is received in response to a request other |
| 3705 | | than GET or HEAD, the user agent &MUST-NOT; automatically redirect the |
| 3706 | | request unless it can be confirmed by the user, since this might |
| 3707 | | change the conditions under which the request was issued. |
| 3708 | | </t> |
| 3709 | | </section> |
| 3710 | | </section> |
| 3711 | | |
| 3712 | | <section title="Client Error 4xx" anchor="status.4xx"> |
| 3713 | | <t> |
| 3714 | | The 4xx class of status code is intended for cases in which the |
| 3715 | | client seems to have erred. Except when responding to a HEAD request, |
| 3716 | | the server &SHOULD; include an entity containing an explanation of the |
| 3717 | | error situation, and whether it is a temporary or permanent |
| 3718 | | condition. These status codes are applicable to any request method. |
| 3719 | | User agents &SHOULD; display any included entity to the user. |
| 3720 | | </t> |
| 3721 | | <t> |
| 3722 | | If the client is sending data, a server implementation using TCP |
| 3723 | | &SHOULD; be careful to ensure that the client acknowledges receipt of |
| 3724 | | the packet(s) containing the response, before the server closes the |
| 3725 | | input connection. If the client continues sending data to the server |
| 3726 | | after the close, the server's TCP stack will send a reset packet to |
| 3727 | | the client, which may erase the client's unacknowledged input buffers |
| 3728 | | before they can be read and interpreted by the HTTP application. |
| 3729 | | </t> |
| 3730 | | |
| 3731 | | <section title="400 Bad Request" anchor="status.400"> |
| 3732 | | <iref primary="true" item="400 Bad Request (status code)" x:for-anchor=""/> |
| 3733 | | <iref primary="true" item="Status Codes" subitem="400 Bad Request" x:for-anchor=""/> |
| 3734 | | <t> |
| 3735 | | The request could not be understood by the server due to malformed |
| 3736 | | syntax. The client &SHOULD-NOT; repeat the request without |
| 3737 | | modifications. |
| 3738 | | </t> |
| 3739 | | </section> |
| 3740 | | |
| 3741 | | <section title="401 Unauthorized" anchor="status.401"> |
| 3742 | | <iref primary="true" item="401 Unauthorized (status code)" x:for-anchor=""/> |
| 3743 | | <iref primary="true" item="Status Codes" subitem="401 Unauthorized" x:for-anchor=""/> |
| 3744 | | <t> |
| 3745 | | The request requires user authentication. The response &MUST; include a |
| 3746 | | WWW-Authenticate header field (<xref target="header.www-authenticate"/>) containing a challenge |
| 3747 | | applicable to the requested resource. The client &MAY; repeat the |
| 3748 | | request with a suitable Authorization header field (<xref target="header.authorization"/>). If |
| 3749 | | the request already included Authorization credentials, then the 401 |
| 3750 | | response indicates that authorization has been refused for those |
| 3751 | | credentials. If the 401 response contains the same challenge as the |
| 3752 | | prior response, and the user agent has already attempted |
| 3753 | | authentication at least once, then the user &SHOULD; be presented the |
| 3754 | | entity that was given in the response, since that entity might |
| 3755 | | include relevant diagnostic information. HTTP access authentication |
| 3756 | | is explained in "HTTP Authentication: Basic and Digest Access |
| 3757 | | Authentication" <xref target="RFC2617"/>. |
| 3758 | | </t> |
| 3759 | | </section> |
| 3760 | | |
| 3761 | | <section title="402 Payment Required" anchor="status.402"> |
| 3762 | | <iref primary="true" item="402 Payment Required (status code)" x:for-anchor=""/> |
| 3763 | | <iref primary="true" item="Status Codes" subitem="402 Payment Required" x:for-anchor=""/> |
| 3764 | | <t> |
| 3765 | | This code is reserved for future use. |
| 3766 | | </t> |
| 3767 | | </section> |
| 3768 | | |
| 3769 | | <section title="403 Forbidden" anchor="status.403"> |
| 3770 | | <iref primary="true" item="403 Forbidden (status code)" x:for-anchor=""/> |
| 3771 | | <iref primary="true" item="Status Codes" subitem="403 Forbidden" x:for-anchor=""/> |
| 3772 | | <t> |
| 3773 | | The server understood the request, but is refusing to fulfill it. |
| 3774 | | Authorization will not help and the request &SHOULD-NOT; be repeated. |
| 3775 | | If the request method was not HEAD and the server wishes to make |
| 3776 | | public why the request has not been fulfilled, it &SHOULD; describe the |
| 3777 | | reason for the refusal in the entity. If the server does not wish to |
| 3778 | | make this information available to the client, the status code 404 |
| 3779 | | (Not Found) can be used instead. |
| 3780 | | </t> |
| 3781 | | </section> |
| 3782 | | |
| 3783 | | <section title="404 Not Found" anchor="status.404"> |
| 3784 | | <iref primary="true" item="404 Not Found (status code)" x:for-anchor=""/> |
| 3785 | | <iref primary="true" item="Status Codes" subitem="404 Not Found" x:for-anchor=""/> |
| 3786 | | <t> |
| 3787 | | The server has not found anything matching the Request-URI. No |
| 3788 | | indication is given of whether the condition is temporary or |
| 3789 | | permanent. The 410 (Gone) status code &SHOULD; be used if the server |
| 3790 | | knows, through some internally configurable mechanism, that an old |
| 3791 | | resource is permanently unavailable and has no forwarding address. |
| 3792 | | This status code is commonly used when the server does not wish to |
| 3793 | | reveal exactly why the request has been refused, or when no other |
| 3794 | | response is applicable. |
| 3795 | | </t> |
| 3796 | | </section> |
| 3797 | | |
| 3798 | | <section title="405 Method Not Allowed" anchor="status.405"> |
| 3799 | | <iref primary="true" item="405 Method Not Allowed (status code)" x:for-anchor=""/> |
| 3800 | | <iref primary="true" item="Status Codes" subitem="405 Method Not Allowed" x:for-anchor=""/> |
| 3801 | | <t> |
| 3802 | | The method specified in the Request-Line is not allowed for the |
| 3803 | | resource identified by the Request-URI. The response &MUST; include an |
| 3804 | | Allow header containing a list of valid methods for the requested |
| 3805 | | resource. |
| 3806 | | </t> |
| 3807 | | </section> |
| 3808 | | |
| 3809 | | <section title="406 Not Acceptable" anchor="status.406"> |
| 3810 | | <iref primary="true" item="406 Not Acceptable (status code)" x:for-anchor=""/> |
| 3811 | | <iref primary="true" item="Status Codes" subitem="406 Not Acceptable" x:for-anchor=""/> |
| 3812 | | <t> |
| 3813 | | The resource identified by the request is only capable of generating |
| 3814 | | response entities which have content characteristics not acceptable |
| 3815 | | according to the accept headers sent in the request. |
| 3816 | | </t> |
| 3817 | | <t> |
| 3818 | | Unless it was a HEAD request, the response &SHOULD; include an entity |
| 3819 | | containing a list of available entity characteristics and location(s) |
| 3820 | | from which the user or user agent can choose the one most |
| 3821 | | appropriate. The entity format is specified by the media type given |
| 3822 | | in the Content-Type header field. Depending upon the format and the |
| 3823 | | capabilities of the user agent, selection of the most appropriate |
| 3824 | | choice &MAY; be performed automatically. However, this specification |
| 3825 | | does not define any standard for such automatic selection. |
| 3826 | | <list><t> |
| 3827 | | <x:h>Note:</x:h> HTTP/1.1 servers are allowed to return responses which are |
| 3828 | | not acceptable according to the accept headers sent in the |
| 3829 | | request. In some cases, this may even be preferable to sending a |
| 3830 | | 406 response. User agents are encouraged to inspect the headers of |
| 3831 | | an incoming response to determine if it is acceptable. |
| 3832 | | </t></list> |
| 3833 | | </t> |
| 3834 | | <t> |
| 3835 | | If the response could be unacceptable, a user agent &SHOULD; |
| 3836 | | temporarily stop receipt of more data and query the user for a |
| 3837 | | decision on further actions. |
| 3838 | | </t> |
| 3839 | | </section> |
| 3840 | | |
| 3841 | | <section title="407 Proxy Authentication Required" anchor="status.407"> |
| 3842 | | <iref primary="true" item="407 Proxy Authentication Required (status code)" x:for-anchor=""/> |
| 3843 | | <iref primary="true" item="Status Codes" subitem="407 Proxy Authentication Required" x:for-anchor=""/> |
| 3844 | | <t> |
| 3845 | | This code is similar to 401 (Unauthorized), but indicates that the |
| 3846 | | client must first authenticate itself with the proxy. The proxy &MUST; |
| 3847 | | return a Proxy-Authenticate header field (<xref target="header.proxy-authenticate"/>) containing a |
| 3848 | | challenge applicable to the proxy for the requested resource. The |
| 3849 | | client &MAY; repeat the request with a suitable Proxy-Authorization |
| 3850 | | header field (<xref target="header.proxy-authorization"/>). HTTP access authentication is explained |
| 3851 | | in "HTTP Authentication: Basic and Digest Access Authentication" |
| 3852 | | <xref target="RFC2617"/>. |
| 3853 | | </t> |
| 3854 | | </section> |
| 3855 | | |
| 3856 | | <section title="408 Request Timeout" anchor="status.408"> |
| 3857 | | <iref primary="true" item="408 Request Timeout (status code)" x:for-anchor=""/> |
| 3858 | | <iref primary="true" item="Status Codes" subitem="408 Request Timeout" x:for-anchor=""/> |
| 3859 | | <t> |
| 3860 | | The client did not produce a request within the time that the server |
| 3861 | | was prepared to wait. The client &MAY; repeat the request without |
| 3862 | | modifications at any later time. |
| 3863 | | </t> |
| 3864 | | </section> |
| 3865 | | |
| 3866 | | <section title="409 Conflict" anchor="status.409"> |
| 3867 | | <iref primary="true" item="409 Conflict (status code)" x:for-anchor=""/> |
| 3868 | | <iref primary="true" item="Status Codes" subitem="409 Conflict" x:for-anchor=""/> |
| 3869 | | <t> |
| 3870 | | The request could not be completed due to a conflict with the current |
| 3871 | | state of the resource. This code is only allowed in situations where |
| 3872 | | it is expected that the user might be able to resolve the conflict |
| 3873 | | and resubmit the request. The response body &SHOULD; include enough |
| 3874 | | information for the user to recognize the source of the conflict. |
| 3875 | | Ideally, the response entity would include enough information for the |
| 3876 | | user or user agent to fix the problem; however, that might not be |
| 3877 | | possible and is not required. |
| 3878 | | </t> |
| 3879 | | <t> |
| 3880 | | Conflicts are most likely to occur in response to a PUT request. For |
| 3881 | | example, if versioning were being used and the entity being PUT |
| 3882 | | included changes to a resource which conflict with those made by an |
| 3883 | | earlier (third-party) request, the server might use the 409 response |
| 3884 | | to indicate that it can't complete the request. In this case, the |
| 3885 | | response entity would likely contain a list of the differences |
| 3886 | | between the two versions in a format defined by the response |
| 3887 | | Content-Type. |
| 3888 | | </t> |
| 3889 | | </section> |
| 3890 | | |
| 3891 | | <section title="410 Gone" anchor="status.410"> |
| 3892 | | <iref primary="true" item="410 Gone (status code)" x:for-anchor=""/> |
| 3893 | | <iref primary="true" item="Status Codes" subitem="410 Gone" x:for-anchor=""/> |
| 3894 | | <t> |
| 3895 | | The requested resource is no longer available at the server and no |
| 3896 | | forwarding address is known. This condition is expected to be |
| 3897 | | considered permanent. Clients with link editing capabilities &SHOULD; |
| 3898 | | delete references to the Request-URI after user approval. If the |
| 3899 | | server does not know, or has no facility to determine, whether or not |
| 3900 | | the condition is permanent, the status code 404 (Not Found) &SHOULD; be |
| 3901 | | used instead. This response is cacheable unless indicated otherwise. |
| 3902 | | </t> |
| 3903 | | <t> |
| 3904 | | The 410 response is primarily intended to assist the task of web |
| 3905 | | maintenance by notifying the recipient that the resource is |
| 3906 | | intentionally unavailable and that the server owners desire that |
| 3907 | | remote links to that resource be removed. Such an event is common for |
| 3908 | | limited-time, promotional services and for resources belonging to |
| 3909 | | individuals no longer working at the server's site. It is not |
| 3910 | | necessary to mark all permanently unavailable resources as "gone" or |
| 3911 | | to keep the mark for any length of time -- that is left to the |
| 3912 | | discretion of the server owner. |
| 3913 | | </t> |
| 3914 | | </section> |
| 3915 | | |
| 3916 | | <section title="411 Length Required" anchor="status.411"> |
| 3917 | | <iref primary="true" item="411 Length Required (status code)" x:for-anchor=""/> |
| 3918 | | <iref primary="true" item="Status Codes" subitem="411 Length Required" x:for-anchor=""/> |
| 3919 | | <t> |
| 3920 | | The server refuses to accept the request without a defined Content-Length. |
| 3921 | | The client &MAY; repeat the request if it adds a valid |
| 3922 | | Content-Length header field containing the length of the message-body |
| 3923 | | in the request message. |
| 3924 | | </t> |
| 3925 | | </section> |
| 3926 | | |
| 3927 | | <section title="412 Precondition Failed" anchor="status.412"> |
| 3928 | | <iref primary="true" item="412 Precondition Failed (status code)" x:for-anchor=""/> |
| 3929 | | <iref primary="true" item="Status Codes" subitem="412 Precondition Failed" x:for-anchor=""/> |
| 3930 | | <t> |
| 3931 | | The precondition given in one or more of the request-header fields |
| 3932 | | evaluated to false when it was tested on the server. This response |
| 3933 | | code allows the client to place preconditions on the current resource |
| 3934 | | metainformation (header field data) and thus prevent the requested |
| 3935 | | method from being applied to a resource other than the one intended. |
| 3936 | | </t> |
| 3937 | | </section> |
| 3938 | | |
| 3939 | | <section title="413 Request Entity Too Large" anchor="status.413"> |
| 3940 | | <iref primary="true" item="413 Request Entity Too Large (status code)" x:for-anchor=""/> |
| 3941 | | <iref primary="true" item="Status Codes" subitem="413 Request Entity Too Large" x:for-anchor=""/> |
| 3942 | | <t> |
| 3943 | | The server is refusing to process a request because the request |
| 3944 | | entity is larger than the server is willing or able to process. The |
| 3945 | | server &MAY; close the connection to prevent the client from continuing |
| 3946 | | the request. |
| 3947 | | </t> |
| 3948 | | <t> |
| 3949 | | If the condition is temporary, the server &SHOULD; include a Retry-After |
| 3950 | | header field to indicate that it is temporary and after what |
| 3951 | | time the client &MAY; try again. |
| 3952 | | </t> |
| 3953 | | </section> |
| 3954 | | |
| 3955 | | <section title="414 Request-URI Too Long" anchor="status.414"> |
| 3956 | | <iref primary="true" item="414 Request-URI Too Long (status code)" x:for-anchor=""/> |
| 3957 | | <iref primary="true" item="Status Codes" subitem="414 Request-URI Too Long" x:for-anchor=""/> |
| 3958 | | <t> |
| 3959 | | The server is refusing to service the request because the Request-URI |
| 3960 | | is longer than the server is willing to interpret. This rare |
| 3961 | | condition is only likely to occur when a client has improperly |
| 3962 | | converted a POST request to a GET request with long query |
| 3963 | | information, when the client has descended into a URI "black hole" of |
| 3964 | | redirection (e.g., a redirected URI prefix that points to a suffix of |
| 3965 | | itself), or when the server is under attack by a client attempting to |
| 3966 | | exploit security holes present in some servers using fixed-length |
| 3967 | | buffers for reading or manipulating the Request-URI. |
| 3968 | | </t> |
| 3969 | | </section> |
| 3970 | | |
| 3971 | | <section title="415 Unsupported Media Type" anchor="status.415"> |
| 3972 | | <iref primary="true" item="415 Unsupported Media Type (status code)" x:for-anchor=""/> |
| 3973 | | <iref primary="true" item="Status Codes" subitem="415 Unsupported Media Type" x:for-anchor=""/> |
| 3974 | | <t> |
| 3975 | | The server is refusing to service the request because the entity of |
| 3976 | | the request is in a format not supported by the requested resource |
| 3977 | | for the requested method. |
| 3978 | | </t> |
| 3979 | | </section> |
| 3980 | | |
| 3981 | | <section title="416 Requested Range Not Satisfiable" anchor="status.416"> |
| 3982 | | <iref primary="true" item="416 Requested Range Not Satisfiable (status code)" x:for-anchor=""/> |
| 3983 | | <iref primary="true" item="Status Codes" subitem="416 Requested Range Not Satisfiable" x:for-anchor=""/> |
| 3984 | | <t> |
| 3985 | | A server &SHOULD; return a response with this status code if a request |
| 3986 | | included a Range request-header field (<xref target="header.range"/>), and none of |
| 3987 | | the range-specifier values in this field overlap the current extent |
| 3988 | | of the selected resource, and the request did not include an If-Range |
| 3989 | | request-header field. (For byte-ranges, this means that the first-byte-pos |
| 3990 | | of all of the byte-range-spec values were greater than the |
| 3991 | | current length of the selected resource.) |
| 3992 | | </t> |
| 3993 | | <t> |
| 3994 | | When this status code is returned for a byte-range request, the |
| 3995 | | response &SHOULD; include a Content-Range entity-header field |
| 3996 | | specifying the current length of the selected resource (see <xref target="header.content-range"/>). |
| 3997 | | This response &MUST-NOT; use the multipart/byteranges content-type. |
| 3998 | | </t> |
| 3999 | | </section> |
| 4000 | | |
| 4001 | | <section title="417 Expectation Failed" anchor="status.417"> |
| 4002 | | <iref primary="true" item="417 Expectation Failed (status code)" x:for-anchor=""/> |
| 4003 | | <iref primary="true" item="Status Codes" subitem="417 Expectation Failed" x:for-anchor=""/> |
| 4004 | | <t> |
| 4005 | | The expectation given in an Expect request-header field (see <xref target="header.expect"/>) |
| 4006 | | could not be met by this server, or, if the server is a proxy, |
| 4007 | | the server has unambiguous evidence that the request could not be met |
| 4008 | | by the next-hop server. |
| 4009 | | </t> |
| 4010 | | </section> |
| 4011 | | </section> |
| 4012 | | |
| 4013 | | <section title="Server Error 5xx" anchor="status.5xx"> |
| 4014 | | <t> |
| 4015 | | Response status codes beginning with the digit "5" indicate cases in |
| 4016 | | which the server is aware that it has erred or is incapable of |
| 4017 | | performing the request. Except when responding to a HEAD request, the |
| 4018 | | server &SHOULD; include an entity containing an explanation of the |
| 4019 | | error situation, and whether it is a temporary or permanent |
| 4020 | | condition. User agents &SHOULD; display any included entity to the |
| 4021 | | user. These response codes are applicable to any request method. |
| 4022 | | </t> |
| 4023 | | |
| 4024 | | <section title="500 Internal Server Error" anchor="status.500"> |
| 4025 | | <iref primary="true" item="500 Internal Server Error (status code)" x:for-anchor=""/> |
| 4026 | | <iref primary="true" item="Status Codes" subitem="500 Internal Server Error" x:for-anchor=""/> |
| 4027 | | <t> |
| 4028 | | The server encountered an unexpected condition which prevented it |
| 4029 | | from fulfilling the request. |
| 4030 | | </t> |
| 4031 | | </section> |
| 4032 | | |
| 4033 | | <section title="501 Not Implemented" anchor="status.501"> |
| 4034 | | <iref primary="true" item="501 Not Implemented (status code)" x:for-anchor=""/> |
| 4035 | | <iref primary="true" item="Status Codes" subitem="501 Not Implemented" x:for-anchor=""/> |
| 4036 | | <t> |
| 4037 | | The server does not support the functionality required to fulfill the |
| 4038 | | request. This is the appropriate response when the server does not |
| 4039 | | recognize the request method and is not capable of supporting it for |
| 4040 | | any resource. |
| 4041 | | </t> |
| 4042 | | </section> |
| 4043 | | |
| 4044 | | <section title="502 Bad Gateway" anchor="status.502"> |
| 4045 | | <iref primary="true" item="502 Bad Gateway (status code)" x:for-anchor=""/> |
| 4046 | | <iref primary="true" item="Status Codes" subitem="502 Bad Gateway" x:for-anchor=""/> |
| 4047 | | <t> |
| 4048 | | The server, while acting as a gateway or proxy, received an invalid |
| 4049 | | response from the upstream server it accessed in attempting to |
| 4050 | | fulfill the request. |
| 4051 | | </t> |
| 4052 | | </section> |
| 4053 | | |
| 4054 | | <section title="503 Service Unavailable" anchor="status.503"> |
| 4055 | | <iref primary="true" item="503 Service Unavailable (status code)" x:for-anchor=""/> |
| 4056 | | <iref primary="true" item="Status Codes" subitem="503 Service Unavailable" x:for-anchor=""/> |
| 4057 | | <t> |
| 4058 | | The server is currently unable to handle the request due to a |
| 4059 | | temporary overloading or maintenance of the server. The implication |
| 4060 | | is that this is a temporary condition which will be alleviated after |
| 4061 | | some delay. If known, the length of the delay &MAY; be indicated in a |
| 4062 | | Retry-After header. If no Retry-After is given, the client &SHOULD; |
| 4063 | | handle the response as it would for a 500 response. |
| 4064 | | <list><t> |
| 4065 | | <x:h>Note:</x:h> The existence of the 503 status code does not imply that a |
| 4066 | | server must use it when becoming overloaded. Some servers may wish |
| 4067 | | to simply refuse the connection. |
| 4068 | | </t></list> |
| 4069 | | </t> |
| 4070 | | </section> |
| 4071 | | |
| 4072 | | <section title="504 Gateway Timeout" anchor="status.504"> |
| 4073 | | <iref primary="true" item="504 Gateway Timeout (status code)" x:for-anchor=""/> |
| 4074 | | <iref primary="true" item="Status Codes" subitem="504 Gateway Timeout" x:for-anchor=""/> |
| 4075 | | <t> |
| 4076 | | The server, while acting as a gateway or proxy, did not receive a |
| 4077 | | timely response from the upstream server specified by the URI (e.g. |
| 4078 | | HTTP, FTP, LDAP) or some other auxiliary server (e.g. DNS) it needed |
| 4079 | | to access in attempting to complete the request. |
| 4080 | | <list><t> |
| 4081 | | <x:h>Note:</x:h> Note to implementors: some deployed proxies are known to |
| 4082 | | return 400 or 500 when DNS lookups time out. |
| 4083 | | </t></list> |
| 4084 | | </t> |
| 4085 | | </section> |
| 4086 | | |
| 4087 | | <section title="505 HTTP Version Not Supported" anchor="status.505"> |
| 4088 | | <iref primary="true" item="505 HTTP Version Not Supported (status code)" x:for-anchor=""/> |
| 4089 | | <iref primary="true" item="Status Codes" subitem="505 HTTP Version Not Supported" x:for-anchor=""/> |
| 4090 | | <t> |
| 4091 | | The server does not support, or refuses to support, the HTTP protocol |
| 4092 | | version that was used in the request message. The server is |
| 4093 | | indicating that it is unable or unwilling to complete the request |
| 4094 | | using the same major version as the client, as described in <xref target="http.version"/>, |
| 4095 | | other than with this error message. The response &SHOULD; contain |
| 4096 | | an entity describing why that version is not supported and what other |
| 4097 | | protocols are supported by that server. |
| 4098 | | </t> |
| 4099 | | |
| 4100 | | </section> |
| 4101 | | </section> |
| 4102 | | </section> |
| 4103 | | |
| 4104 | | |
| 4105 | | <section title="Access Authentication" anchor="access.authentication"> |
| 4106 | | <t> |
| 4107 | | HTTP provides several &OPTIONAL; challenge-response authentication |
| 4108 | | |
| 4109 | | mechanisms which can be used by a server to challenge a client |
| 4110 | | request and by a client to provide authentication information. The |
| 4111 | | general framework for access authentication, and the specification of |
| 4112 | | "basic" and "digest" authentication, are specified in "HTTP |
| 4113 | | Authentication: Basic and Digest Access Authentication" <xref target="RFC2617"/>. This |
| 4114 | | specification adopts the definitions of "challenge" and "credentials" |
| 4115 | | from that specification. |
| 4116 | | </t> |
| 4117 | | </section> |
| 4118 | | |
| 4119 | | <section title="Content Negotiation" anchor="content.negotiation"> |
| 4120 | | <t> |
| 4121 | | Most HTTP responses include an entity which contains information for |
| 4122 | | interpretation by a human user. Naturally, it is desirable to supply |
| 4123 | | the user with the "best available" entity corresponding to the |
| 4124 | | request. Unfortunately for servers and caches, not all users have the |
| 4125 | | same preferences for what is "best," and not all user agents are |
| 4126 | | equally capable of rendering all entity types. For that reason, HTTP |
| 4127 | | has provisions for several mechanisms for "content negotiation" -- |
| 4128 | | the process of selecting the best representation for a given response |
| 4129 | | when there are multiple representations available. |
| 4130 | | <list><t> |
| 4131 | | <x:h>Note:</x:h> This is not called "format negotiation" because the |
| 4132 | | alternate representations may be of the same media type, but use |
| 4133 | | different capabilities of that type, be in different languages, |
| 4134 | | etc. |
| 4135 | | </t></list> |
| 4136 | | </t> |
| 4137 | | <t> |
| 4138 | | Any response containing an entity-body &MAY; be subject to negotiation, |
| 4139 | | including error responses. |
| 4140 | | </t> |
| 4141 | | <t> |
| 4142 | | There are two kinds of content negotiation which are possible in |
| 4143 | | HTTP: server-driven and agent-driven negotiation. These two kinds of |
| 4144 | | negotiation are orthogonal and thus may be used separately or in |
| 4145 | | combination. One method of combination, referred to as transparent |
| 4146 | | negotiation, occurs when a cache uses the agent-driven negotiation |
| 4147 | | information provided by the origin server in order to provide |
| 4148 | | server-driven negotiation for subsequent requests. |
| 4149 | | </t> |
| 4150 | | |
| 4151 | | <section title="Server-driven Negotiation" anchor="server-driven.negotiation"> |
| 4152 | | <t> |
| 4153 | | If the selection of the best representation for a response is made by |
| 4154 | | an algorithm located at the server, it is called server-driven |
| 4155 | | negotiation. Selection is based on the available representations of |
| 4156 | | the response (the dimensions over which it can vary; e.g. language, |
| 4157 | | content-coding, etc.) and the contents of particular header fields in |
| 4158 | | the request message or on other information pertaining to the request |
| 4159 | | (such as the network address of the client). |
| 4160 | | </t> |
| 4161 | | <t> |
| 4162 | | Server-driven negotiation is advantageous when the algorithm for |
| 4163 | | selecting from among the available representations is difficult to |
| 4164 | | describe to the user agent, or when the server desires to send its |
| 4165 | | "best guess" to the client along with the first response (hoping to |
| 4166 | | avoid the round-trip delay of a subsequent request if the "best |
| 4167 | | guess" is good enough for the user). In order to improve the server's |
| 4168 | | guess, the user agent &MAY; include request header fields (Accept, |
| 4169 | | Accept-Language, Accept-Encoding, etc.) which describe its |
| 4170 | | preferences for such a response. |
| 4171 | | </t> |
| 4172 | | <t> |
| 4173 | | Server-driven negotiation has disadvantages: |
| 4174 | | <list style="numbers"> |
| 4175 | | <t> |
| 4176 | | It is impossible for the server to accurately determine what |
| 4177 | | might be "best" for any given user, since that would require |
| 4178 | | complete knowledge of both the capabilities of the user agent |
| 4179 | | and the intended use for the response (e.g., does the user want |
| 4180 | | to view it on screen or print it on paper?). |
| 4181 | | </t> |
| 4182 | | <t> |
| 4183 | | Having the user agent describe its capabilities in every |
| 4184 | | request can be both very inefficient (given that only a small |
| 4185 | | percentage of responses have multiple representations) and a |
| 4186 | | potential violation of the user's privacy. |
| 4187 | | </t> |
| 4188 | | <t> |
| 4189 | | It complicates the implementation of an origin server and the |
| 4190 | | algorithms for generating responses to a request. |
| 4191 | | </t> |
| 4192 | | <t> |
| 4193 | | It may limit a public cache's ability to use the same response |
| 4194 | | for multiple user's requests. |
| 4195 | | </t> |
| 4196 | | </list> |
| 4197 | | </t> |
| 4198 | | <t> |
| 4199 | | HTTP/1.1 includes the following request-header fields for enabling |
| 4200 | | server-driven negotiation through description of user agent |
| 4201 | | capabilities and user preferences: Accept (<xref target="header.accept"/>), Accept-Charset |
| 4202 | | (<xref target="header.accept-charset"/>), Accept-Encoding (<xref target="header.accept-encoding"/>), Accept-Language |
| 4203 | | (<xref target="header.accept-language"/>), and User-Agent (<xref target="header.user-agent"/>). However, an |
| 4204 | | origin server is not limited to these dimensions and &MAY; vary the |
| 4205 | | response based on any aspect of the request, including information |
| 4206 | | outside the request-header fields or within extension header fields |
| 4207 | | not defined by this specification. |
| 4208 | | </t> |
| 4209 | | <t> |
| 4210 | | The Vary header field can be used to express the parameters the |
| 4211 | | server uses to select a representation that is subject to server-driven |
| 4212 | | negotiation. See <xref target="caching.negotiated.responses"/> for use of the Vary header field |
| 4213 | | by caches and <xref target="header.vary"/> for use of the Vary header field by |
| 4214 | | servers. |
| 4215 | | </t> |
| 4216 | | </section> |
| 4217 | | |
| 4218 | | <section title="Agent-driven Negotiation" anchor="agent-driven.negotiation"> |
| 4219 | | <t> |
| 4220 | | With agent-driven negotiation, selection of the best representation |
| 4221 | | for a response is performed by the user agent after receiving an |
| 4222 | | initial response from the origin server. Selection is based on a list |
| 4223 | | of the available representations of the response included within the |
| 4224 | | header fields or entity-body of the initial response, with each |
| 4225 | | representation identified by its own URI. Selection from among the |
| 4226 | | representations may be performed automatically (if the user agent is |
| 4227 | | capable of doing so) or manually by the user selecting from a |
| 4228 | | generated (possibly hypertext) menu. |
| 4229 | | </t> |
| 4230 | | <t> |
| 4231 | | Agent-driven negotiation is advantageous when the response would vary |
| 4232 | | over commonly-used dimensions (such as type, language, or encoding), |
| 4233 | | when the origin server is unable to determine a user agent's |
| 4234 | | capabilities from examining the request, and generally when public |
| 4235 | | caches are used to distribute server load and reduce network usage. |
| 4236 | | </t> |
| 4237 | | <t> |
| 4238 | | Agent-driven negotiation suffers from the disadvantage of needing a |
| 4239 | | second request to obtain the best alternate representation. This |
| 4240 | | second request is only efficient when caching is used. In addition, |
| 4241 | | this specification does not define any mechanism for supporting |
| 4242 | | automatic selection, though it also does not prevent any such |
| 4243 | | mechanism from being developed as an extension and used within |
| 4244 | | HTTP/1.1. |
| 4245 | | </t> |
| 4246 | | <t> |
| 4247 | | HTTP/1.1 defines the 300 (Multiple Choices) and 406 (Not Acceptable) |
| 4248 | | status codes for enabling agent-driven negotiation when the server is |
| 4249 | | unwilling or unable to provide a varying response using server-driven |
| 4250 | | negotiation. |
| 4251 | | </t> |
| 4252 | | </section> |
| 4253 | | |
| 4254 | | <section title="Transparent Negotiation" anchor="transparent.negotiation"> |
| 4255 | | <t> |
| 4256 | | Transparent negotiation is a combination of both server-driven and |
| 4257 | | agent-driven negotiation. When a cache is supplied with a form of the |
| 4258 | | list of available representations of the response (as in agent-driven |
| 4259 | | negotiation) and the dimensions of variance are completely understood |
| 4260 | | by the cache, then the cache becomes capable of performing server-driven |
| 4261 | | negotiation on behalf of the origin server for subsequent |
| 4262 | | requests on that resource. |
| 4263 | | </t> |
| 4264 | | <t> |
| 4265 | | Transparent negotiation has the advantage of distributing the |
| 4266 | | negotiation work that would otherwise be required of the origin |
| 4267 | | server and also removing the second request delay of agent-driven |
| 4268 | | negotiation when the cache is able to correctly guess the right |
| 4269 | | response. |
| 4270 | | </t> |
| 4271 | | <t> |
| 4272 | | This specification does not define any mechanism for transparent |
| 4273 | | negotiation, though it also does not prevent any such mechanism from |
| 4274 | | being developed as an extension that could be used within HTTP/1.1. |
| 4275 | | </t> |
| 4276 | | </section> |
| 4277 | | </section> |
| 4278 | | |
| 4279 | | |
| 4280 | | <section title="Caching in HTTP" anchor="caching"> |
| 4281 | | |
| 4282 | | <t> |
| 4283 | | HTTP is typically used for distributed information systems, where |
| 4284 | | performance can be improved by the use of response caches. The |
| 4285 | | HTTP/1.1 protocol includes a number of elements intended to make |
| 4286 | | caching work as well as possible. Because these elements are |
| 4287 | | inextricable from other aspects of the protocol, and because they |
| 4288 | | interact with each other, it is useful to describe the basic caching |
| 4289 | | design of HTTP separately from the detailed descriptions of methods, |
| 4290 | | headers, response codes, etc. |
| 4291 | | </t> |
| 4292 | | <t> |
| 4293 | | Caching would be useless if it did not significantly improve |
| 4294 | | performance. The goal of caching in HTTP/1.1 is to eliminate the need |
| 4295 | | to send requests in many cases, and to eliminate the need to send |
| 4296 | | full responses in many other cases. The former reduces the number of |
| 4297 | | network round-trips required for many operations; we use an |
| 4298 | | "expiration" mechanism for this purpose (see <xref target="expiration.model"/>). The |
| 4299 | | latter reduces network bandwidth requirements; we use a "validation" |
| 4300 | | mechanism for this purpose (see <xref target="validation.model"/>). |
| 4301 | | </t> |
| 4302 | | <t> |
| 4303 | | Requirements for performance, availability, and disconnected |
| 4304 | | operation require us to be able to relax the goal of semantic |
| 4305 | | transparency. The HTTP/1.1 protocol allows origin servers, caches, |
| 4306 | | and clients to explicitly reduce transparency when necessary. |
| 4307 | | However, because non-transparent operation may confuse non-expert |
| 4308 | | users, and might be incompatible with certain server applications |
| 4309 | | (such as those for ordering merchandise), the protocol requires that |
| 4310 | | transparency be relaxed |
| 4311 | | <list style="symbols"> |
| 4312 | | <t>only by an explicit protocol-level request when relaxed by |
| 4313 | | client or origin server</t> |
| 4314 | | |
| 4315 | | <t>only with an explicit warning to the end user when relaxed by |
| 4316 | | cache or client</t> |
| 4317 | | </list> |
| 4318 | | </t> |
| 4319 | | <t> |
| 4320 | | Therefore, the HTTP/1.1 protocol provides these important elements: |
| 4321 | | <list style="numbers"> |
| 4322 | | <t>Protocol features that provide full semantic transparency when |
| 4323 | | this is required by all parties.</t> |
| 4324 | | |
| 4325 | | <t>Protocol features that allow an origin server or user agent to |
| 4326 | | explicitly request and control non-transparent operation.</t> |
| 4327 | | |
| 4328 | | <t>Protocol features that allow a cache to attach warnings to |
| 4329 | | responses that do not preserve the requested approximation of |
| 4330 | | semantic transparency.</t> |
| 4331 | | </list> |
| 4332 | | </t> |
| 4333 | | <t> |
| 4334 | | A basic principle is that it must be possible for the clients to |
| 4335 | | detect any potential relaxation of semantic transparency. |
| 4336 | | <list><t> |
| 4337 | | <x:h>Note:</x:h> The server, cache, or client implementor might be faced with |
| 4338 | | design decisions not explicitly discussed in this specification. |
| 4339 | | If a decision might affect semantic transparency, the implementor |
| 4340 | | ought to err on the side of maintaining transparency unless a |
| 4341 | | careful and complete analysis shows significant benefits in |
| 4342 | | breaking transparency. |
| 4343 | | </t></list> |
| 4344 | | </t> |
| 4345 | | |
| 4346 | | <section title=""> |
| 4347 | | |
| 4348 | | <section title="Cache Correctness" anchor="cache.correctness"> |
| 4349 | | <t> |
| 4350 | | A correct cache &MUST; respond to a request with the most up-to-date |
| 4351 | | response held by the cache that is appropriate to the request (see |
| 4352 | | sections <xref target="disambiguating.expiration.values" format="counter"/>, |
| 4353 | | <xref target="disambiguating.multiple.responses" format="counter"/>, |
| 4354 | | and <xref target="cache.replacement" format="counter"/>) which meets one of the following |
| 4355 | | conditions: |
| 4356 | | <list style="numbers"> |
| 4357 | | <t>It has been checked for equivalence with what the origin server |
| 4358 | | would have returned by revalidating the response with the |
| 4359 | | origin server (<xref target="validation.model"/>);</t> |
| 4360 | | |
| 4361 | | <t>It is "fresh enough" (see <xref target="expiration.model"/>). In the default case, |
| 4362 | | this means it meets the least restrictive freshness requirement |
| 4363 | | of the client, origin server, and cache (see <xref target="header.cache-control"/>); if |
| 4364 | | the origin server so specifies, it is the freshness requirement |
| 4365 | | of the origin server alone. |
| 4366 | | |
| 4367 | | If a stored response is not "fresh enough" by the most |
| 4368 | | restrictive freshness requirement of both the client and the |
| 4369 | | origin server, in carefully considered circumstances the cache |
| 4370 | | &MAY; still return the response with the appropriate Warning |
| 4371 | | header (see section <xref target="exceptions.to.the.rules.and.warnings" format="counter"/> |
| 4372 | | and <xref target="header.warning" format="counter"/>), unless such a response |
| 4373 | | is prohibited (e.g., by a "no-store" cache-directive, or by a |
| 4374 | | "no-cache" cache-request-directive; see <xref target="header.cache-control"/>).</t> |
| 4375 | | |
| 4376 | | <t>It is an appropriate 304 (Not Modified), 305 (Proxy Redirect), |
| 4377 | | or error (4xx or 5xx) response message.</t> |
| 4378 | | </list> |
| 4379 | | </t> |
| 4380 | | <t> |
| 4381 | | If the cache can not communicate with the origin server, then a |
| 4382 | | correct cache &SHOULD; respond as above if the response can be |
| 4383 | | correctly served from the cache; if not it &MUST; return an error or |
| 4384 | | warning indicating that there was a communication failure. |
| 4385 | | </t> |
| 4386 | | <t> |
| 4387 | | If a cache receives a response (either an entire response, or a 304 |
| 4388 | | (Not Modified) response) that it would normally forward to the |
| 4389 | | requesting client, and the received response is no longer fresh, the |
| 4390 | | cache &SHOULD; forward it to the requesting client without adding a new |
| 4391 | | Warning (but without removing any existing Warning headers). A cache |
| 4392 | | &SHOULD-NOT; attempt to revalidate a response simply because that |
| 4393 | | response became stale in transit; this might lead to an infinite |
| 4394 | | loop. A user agent that receives a stale response without a Warning |
| 4395 | | &MAY; display a warning indication to the user. |
| 4396 | | </t> |
| 4397 | | </section> |
| 4398 | | |
| 4399 | | <section title="Warnings" anchor="warnings"> |
| 4400 | | <t> |
| 4401 | | Whenever a cache returns a response that is neither first-hand nor |
| 4402 | | "fresh enough" (in the sense of condition 2 in <xref target="cache.correctness"/>), it |
| 4403 | | &MUST; attach a warning to that effect, using a Warning general-header. |
| 4404 | | The Warning header and the currently defined warnings are described |
| 4405 | | in <xref target="header.warning"/>. The warning allows clients to take appropriate |
| 4406 | | action. |
| 4407 | | </t> |
| 4408 | | <t> |
| 4409 | | Warnings &MAY; be used for other purposes, both cache-related and |
| 4410 | | otherwise. The use of a warning, rather than an error status code, |
| 4411 | | distinguish these responses from true failures. |
| 4412 | | </t> |
| 4413 | | <t> |
| 4414 | | Warnings are assigned three digit warn-codes. The first digit |
| 4415 | | indicates whether the Warning &MUST; or &MUST-NOT; be deleted from a |
| 4416 | | stored cache entry after a successful revalidation: |
| 4417 | | </t> |
| 4418 | | <t> |
| 4419 | | <list style="hanging"> |
| 4420 | | <t hangText="1xx">Warnings that describe the freshness or revalidation status of |
| 4421 | | the response, and so &MUST; be deleted after a successful |
| 4422 | | revalidation. 1XX warn-codes &MAY; be generated by a cache only when |
| 4423 | | validating a cached entry. It &MUST-NOT; be generated by clients.</t> |
| 4424 | | |
| 4425 | | <t hangText="2xx">Warnings that describe some aspect of the entity body or entity |
| 4426 | | headers that is not rectified by a revalidation (for example, a |
| 4427 | | lossy compression of the entity bodies) and which &MUST-NOT; be |
| 4428 | | deleted after a successful revalidation.</t> |
| 4429 | | </list> |
| 4430 | | </t> |
| 4431 | | <t> |
| 4432 | | See <xref target="header.warning"/> for the definitions of the codes themselves. |
| 4433 | | </t> |
| 4434 | | <t> |
| 4435 | | HTTP/1.0 caches will cache all Warnings in responses, without |
| 4436 | | deleting the ones in the first category. Warnings in responses that |
| 4437 | | are passed to HTTP/1.0 caches carry an extra warning-date field, |
| 4438 | | which prevents a future HTTP/1.1 recipient from believing an |
| 4439 | | erroneously cached Warning. |
| 4440 | | </t> |
| 4441 | | <t> |
| 4442 | | Warnings also carry a warning text. The text &MAY; be in any |
| 4443 | | appropriate natural language (perhaps based on the client's Accept |
| 4444 | | headers), and include an &OPTIONAL; indication of what character set is |
| 4445 | | used. |
| 4446 | | </t> |
| 4447 | | <t> |
| 4448 | | Multiple warnings &MAY; be attached to a response (either by the origin |
| 4449 | | server or by a cache), including multiple warnings with the same code |
| 4450 | | number. For example, a server might provide the same warning with |
| 4451 | | texts in both English and Basque. |
| 4452 | | </t> |
| 4453 | | <t> |
| 4454 | | When multiple warnings are attached to a response, it might not be |
| 4455 | | practical or reasonable to display all of them to the user. This |
| 4456 | | version of HTTP does not specify strict priority rules for deciding |
| 4457 | | which warnings to display and in what order, but does suggest some |
| 4458 | | heuristics. |
| 4459 | | </t> |
| 4460 | | </section> |
| 4461 | | |
| 4462 | | <section title="Cache-control Mechanisms" anchor="cache-control.mechanisms"> |
| 4463 | | <t> |
| 4464 | | The basic cache mechanisms in HTTP/1.1 (server-specified expiration |
| 4465 | | times and validators) are implicit directives to caches. In some |
| 4466 | | cases, a server or client might need to provide explicit directives |
| 4467 | | to the HTTP caches. We use the Cache-Control header for this purpose. |
| 4468 | | </t> |
| 4469 | | <t> |
| 4470 | | The Cache-Control header allows a client or server to transmit a |
| 4471 | | variety of directives in either requests or responses. These |
| 4472 | | directives typically override the default caching algorithms. As a |
| 4473 | | general rule, if there is any apparent conflict between header |
| 4474 | | values, the most restrictive interpretation is applied (that is, the |
| 4475 | | one that is most likely to preserve semantic transparency). However, |
| 4476 | | in some cases, cache-control directives are explicitly specified as |
| 4477 | | weakening the approximation of semantic transparency (for example, |
| 4478 | | "max-stale" or "public"). |
| 4479 | | </t> |
| 4480 | | <t> |
| 4481 | | The cache-control directives are described in detail in <xref target="header.cache-control"/>. |
| 4482 | | </t> |
| 4483 | | </section> |
| 4484 | | |
| 4485 | | <section title="Explicit User Agent Warnings" anchor="explicit.ua.warnings"> |
| 4486 | | <t> |
| 4487 | | Many user agents make it possible for users to override the basic |
| 4488 | | caching mechanisms. For example, the user agent might allow the user |
| 4489 | | to specify that cached entities (even explicitly stale ones) are |
| 4490 | | never validated. Or the user agent might habitually add "Cache-Control: |
| 4491 | | max-stale=3600" to every request. The user agent &SHOULD-NOT; |
| 4492 | | default to either non-transparent behavior, or behavior that results |
| 4493 | | in abnormally ineffective caching, but &MAY; be explicitly configured |
| 4494 | | to do so by an explicit action of the user. |
| 4495 | | </t> |
| 4496 | | <t> |
| 4497 | | If the user has overridden the basic caching mechanisms, the user |
| 4498 | | agent &SHOULD; explicitly indicate to the user whenever this results in |
| 4499 | | the display of information that might not meet the server's |
| 4500 | | transparency requirements (in particular, if the displayed entity is |
| 4501 | | known to be stale). Since the protocol normally allows the user agent |
| 4502 | | to determine if responses are stale or not, this indication need only |
| 4503 | | be displayed when this actually happens. The indication need not be a |
| 4504 | | dialog box; it could be an icon (for example, a picture of a rotting |
| 4505 | | fish) or some other indicator. |
| 4506 | | </t> |
| 4507 | | <t> |
| 4508 | | If the user has overridden the caching mechanisms in a way that would |
| 4509 | | abnormally reduce the effectiveness of caches, the user agent &SHOULD; |
| 4510 | | continually indicate this state to the user (for example, by a |
| 4511 | | display of a picture of currency in flames) so that the user does not |
| 4512 | | inadvertently consume excess resources or suffer from excessive |
| 4513 | | latency. |
| 4514 | | </t> |
| 4515 | | </section> |
| 4516 | | |
| 4517 | | <section title="Exceptions to the Rules and Warnings" anchor="exceptions.to.the.rules.and.warnings"> |
| 4518 | | <t> |
| 4519 | | In some cases, the operator of a cache &MAY; choose to configure it to |
| 4520 | | return stale responses even when not requested by clients. This |
| 4521 | | decision ought not be made lightly, but may be necessary for reasons |
| 4522 | | of availability or performance, especially when the cache is poorly |
| 4523 | | connected to the origin server. Whenever a cache returns a stale |
| 4524 | | response, it &MUST; mark it as such (using a Warning header) enabling |
| 4525 | | the client software to alert the user that there might be a potential |
| 4526 | | problem. |
| 4527 | | </t> |
| 4528 | | <t> |
| 4529 | | It also allows the user agent to take steps to obtain a first-hand or |
| 4530 | | fresh response. For this reason, a cache &SHOULD-NOT; return a stale |
| 4531 | | response if the client explicitly requests a first-hand or fresh one, |
| 4532 | | unless it is impossible to comply for technical or policy reasons. |
| 4533 | | </t> |
| 4534 | | </section> |
| 4535 | | |
| 4536 | | <section title="Client-controlled Behavior" anchor="client-controlled.behavior"> |
| 4537 | | <t> |
| 4538 | | While the origin server (and to a lesser extent, intermediate caches, |
| 4539 | | by their contribution to the age of a response) are the primary |
| 4540 | | source of expiration information, in some cases the client might need |
| 4541 | | to control a cache's decision about whether to return a cached |
| 4542 | | response without validating it. Clients do this using several |
| 4543 | | directives of the Cache-Control header. |
| 4544 | | </t> |
| 4545 | | <t> |
| 4546 | | A client's request &MAY; specify the maximum age it is willing to |
| 4547 | | accept of an unvalidated response; specifying a value of zero forces |
| 4548 | | the cache(s) to revalidate all responses. A client &MAY; also specify |
| 4549 | | the minimum time remaining before a response expires. Both of these |
| 4550 | | options increase constraints on the behavior of caches, and so cannot |
| 4551 | | further relax the cache's approximation of semantic transparency. |
| 4552 | | </t> |
| 4553 | | <t> |
| 4554 | | A client &MAY; also specify that it will accept stale responses, up to |
| 4555 | | some maximum amount of staleness. This loosens the constraints on the |
| 4556 | | caches, and so might violate the origin server's specified |
| 4557 | | constraints on semantic transparency, but might be necessary to |
| 4558 | | support disconnected operation, or high availability in the face of |
| 4559 | | poor connectivity. |
| 4560 | | </t> |
| 4561 | | </section> |
| 4562 | | </section> |
| 4563 | | |
| 4564 | | <section title="Expiration Model" anchor="expiration.model"> |
| 4565 | | |
| 4566 | | <section title="Server-Specified Expiration" anchor="server-specified.expiration"> |
| 4567 | | <t> |
| 4568 | | HTTP caching works best when caches can entirely avoid making |
| 4569 | | requests to the origin server. The primary mechanism for avoiding |
| 4570 | | requests is for an origin server to provide an explicit expiration |
| 4571 | | time in the future, indicating that a response &MAY; be used to satisfy |
| 4572 | | subsequent requests. In other words, a cache can return a fresh |
| 4573 | | response without first contacting the server. |
| 4574 | | </t> |
| 4575 | | <t> |
| 4576 | | Our expectation is that servers will assign future explicit |
| 4577 | | expiration times to responses in the belief that the entity is not |
| 4578 | | likely to change, in a semantically significant way, before the |
| 4579 | | expiration time is reached. This normally preserves semantic |
| 4580 | | transparency, as long as the server's expiration times are carefully |
| 4581 | | chosen. |
| 4582 | | </t> |
| 4583 | | <t> |
| 4584 | | The expiration mechanism applies only to responses taken from a cache |
| 4585 | | and not to first-hand responses forwarded immediately to the |
| 4586 | | requesting client. |
| 4587 | | </t> |
| 4588 | | <t> |
| 4589 | | If an origin server wishes to force a semantically transparent cache |
| 4590 | | to validate every request, it &MAY; assign an explicit expiration time |
| 4591 | | in the past. This means that the response is always stale, and so the |
| 4592 | | cache &SHOULD; validate it before using it for subsequent requests. See |
| 4593 | | <xref target="cache.revalidation.and.reload.controls"/> for a more restrictive way to force revalidation. |
| 4594 | | </t> |
| 4595 | | <t> |
| 4596 | | If an origin server wishes to force any HTTP/1.1 cache, no matter how |
| 4597 | | it is configured, to validate every request, it &SHOULD; use the "must-revalidate" |
| 4598 | | cache-control directive (see <xref target="header.cache-control"/>). |
| 4599 | | </t> |
| 4600 | | <t> |
| 4601 | | Servers specify explicit expiration times using either the Expires |
| 4602 | | header, or the max-age directive of the Cache-Control header. |
| 4603 | | </t> |
| 4604 | | <t> |
| 4605 | | An expiration time cannot be used to force a user agent to refresh |
| 4606 | | its display or reload a resource; its semantics apply only to caching |
| 4607 | | mechanisms, and such mechanisms need only check a resource's |
| 4608 | | expiration status when a new request for that resource is initiated. |
| 4609 | | See <xref target="history.lists"/> for an explanation of the difference between caches |
| 4610 | | and history mechanisms. |
| 4611 | | </t> |
| 4612 | | </section> |
| 4613 | | |
| 4614 | | <section title="Heuristic Expiration" anchor="heuristic.expiration"> |
| 4615 | | <t> |
| 4616 | | Since origin servers do not always provide explicit expiration times, |
| 4617 | | HTTP caches typically assign heuristic expiration times, employing |
| 4618 | | algorithms that use other header values (such as the Last-Modified |
| 4619 | | time) to estimate a plausible expiration time. The HTTP/1.1 |
| 4620 | | specification does not provide specific algorithms, but does impose |
| 4621 | | worst-case constraints on their results. Since heuristic expiration |
| 4622 | | times might compromise semantic transparency, they ought to used |
| 4623 | | cautiously, and we encourage origin servers to provide explicit |
| 4624 | | expiration times as much as possible. |
| 4625 | | </t> |
| 4626 | | </section> |
| 4627 | | |
| 4628 | | <section title="Age Calculations" anchor="age.calculations"> |
| 4629 | | <t> |
| 4630 | | In order to know if a cached entry is fresh, a cache needs to know if |
| 4631 | | its age exceeds its freshness lifetime. We discuss how to calculate |
| 4632 | | the latter in <xref target="expiration.calculations"/>; this section describes how to calculate |
| 4633 | | the age of a response or cache entry. |
| 4634 | | </t> |
| 4635 | | <t> |
| 4636 | | In this discussion, we use the term "now" to mean "the current value |
| 4637 | | of the clock at the host performing the calculation." Hosts that use |
| 4638 | | HTTP, but especially hosts running origin servers and caches, &SHOULD; |
| 4639 | | use NTP <xref target="RFC1305"/> or some similar protocol to synchronize their clocks to |
| 4640 | | a globally accurate time standard. |
| 4641 | | </t> |
| 4642 | | <t> |
| 4643 | | HTTP/1.1 requires origin servers to send a Date header, if possible, |
| 4644 | | with every response, giving the time at which the response was |
| 4645 | | generated (see <xref target="header.date"/>). We use the term "date_value" to denote |
| 4646 | | the value of the Date header, in a form appropriate for arithmetic |
| 4647 | | operations. |
| 4648 | | </t> |
| 4649 | | <t> |
| 4650 | | HTTP/1.1 uses the Age response-header to convey the estimated age of |
| 4651 | | the response message when obtained from a cache. The Age field value |
| 4652 | | is the cache's estimate of the amount of time since the response was |
| 4653 | | generated or revalidated by the origin server. |
| 4654 | | </t> |
| 4655 | | <t> |
| 4656 | | In essence, the Age value is the sum of the time that the response |
| 4657 | | has been resident in each of the caches along the path from the |
| 4658 | | origin server, plus the amount of time it has been in transit along |
| 4659 | | network paths. |
| 4660 | | </t> |
| 4661 | | <t> |
| 4662 | | We use the term "age_value" to denote the value of the Age header, in |
| 4663 | | a form appropriate for arithmetic operations. |
| 4664 | | </t> |
| 4665 | | <t> |
| 4666 | | A response's age can be calculated in two entirely independent ways: |
| 4667 | | <list style="numbers"> |
| 4668 | | <t>now minus date_value, if the local clock is reasonably well |
| 4669 | | synchronized to the origin server's clock. If the result is |
| 4670 | | negative, the result is replaced by zero.</t> |
| 4671 | | |
| 4672 | | <t>age_value, if all of the caches along the response path |
| 4673 | | implement HTTP/1.1.</t> |
| 4674 | | </list> |
| 4675 | | </t> |
| 4676 | | <t> |
| 4677 | | Given that we have two independent ways to compute the age of a |
| 4678 | | response when it is received, we can combine these as |
| 4679 | | </t> |
| 4680 | | <figure><artwork type="code"> |
| 4681 | | corrected_received_age = max(now - date_value, age_value) |
| 4682 | | </artwork></figure> |
| 4683 | | <t> |
| 4684 | | and as long as we have either nearly synchronized clocks or all-HTTP/1.1 |
| 4685 | | paths, one gets a reliable (conservative) result. |
| 4686 | | </t> |
| 4687 | | <t> |
| 4688 | | Because of network-imposed delays, some significant interval might |
| 4689 | | pass between the time that a server generates a response and the time |
| 4690 | | it is received at the next outbound cache or client. If uncorrected, |
| 4691 | | this delay could result in improperly low ages. |
| 4692 | | </t> |
| 4693 | | <t> |
| 4694 | | Because the request that resulted in the returned Age value must have |
| 4695 | | been initiated prior to that Age value's generation, we can correct |
| 4696 | | for delays imposed by the network by recording the time at which the |
| 4697 | | request was initiated. Then, when an Age value is received, it &MUST; |
| 4698 | | be interpreted relative to the time the request was initiated, not |
| 4699 | | the time that the response was received. This algorithm results in |
| 4700 | | conservative behavior no matter how much delay is experienced. So, we |
| 4701 | | compute: |
| 4702 | | </t> |
| 4703 | | <figure><artwork type="code"> |
| 4704 | | corrected_initial_age = corrected_received_age |
| 4705 | | + (now - request_time) |
| 4706 | | </artwork></figure> |
| 4707 | | <t> |
| 4708 | | where "request_time" is the time (according to the local clock) when |
| 4709 | | the request that elicited this response was sent. |
| 4710 | | </t> |
| 4711 | | <t> |
| 4712 | | Summary of age calculation algorithm, when a cache receives a |
| 4713 | | response: |
| 4714 | | </t> |
| 4715 | | <figure><artwork type="code"> |
| 4716 | | /* |
| 4717 | | * age_value |
| 4718 | | * is the value of Age: header received by the cache with |
| 4719 | | * this response. |
| 4720 | | * date_value |
| 4721 | | * is the value of the origin server's Date: header |
| 4722 | | * request_time |
| 4723 | | * is the (local) time when the cache made the request |
| 4724 | | * that resulted in this cached response |
| 4725 | | * response_time |
| 4726 | | * is the (local) time when the cache received the |
| 4727 | | * response |
| 4728 | | * now |
| 4729 | | * is the current (local) time |
| 4730 | | */ |
| 4731 | | |
| 4732 | | apparent_age = max(0, response_time - date_value); |
| 4733 | | corrected_received_age = max(apparent_age, age_value); |
| 4734 | | response_delay = response_time - request_time; |
| 4735 | | corrected_initial_age = corrected_received_age + response_delay; |
| 4736 | | resident_time = now - response_time; |
| 4737 | | current_age = corrected_initial_age + resident_time; |
| 4738 | | </artwork></figure> |
| 4739 | | <t> |
| 4740 | | The current_age of a cache entry is calculated by adding the amount |
| 4741 | | of time (in seconds) since the cache entry was last validated by the |
| 4742 | | origin server to the corrected_initial_age. When a response is |
| 4743 | | generated from a cache entry, the cache &MUST; include a single Age |
| 4744 | | header field in the response with a value equal to the cache entry's |
| 4745 | | current_age. |
| 4746 | | </t> |
| 4747 | | <t> |
| 4748 | | The presence of an Age header field in a response implies that a |
| 4749 | | response is not first-hand. However, the converse is not true, since |
| 4750 | | the lack of an Age header field in a response does not imply that the |
| 4751 | | response is first-hand unless all caches along the request path are |
| 4752 | | compliant with HTTP/1.1 (i.e., older HTTP caches did not implement |
| 4753 | | the Age header field). |
| 4754 | | </t> |
| 4755 | | </section> |
| 4756 | | |
| 4757 | | <section title="Expiration Calculations" anchor="expiration.calculations"> |
| 4758 | | <t> |
| 4759 | | In order to decide whether a response is fresh or stale, we need to |
| 4760 | | compare its freshness lifetime to its age. The age is calculated as |
| 4761 | | described in <xref target="age.calculations"/>; this section describes how to calculate |
| 4762 | | the freshness lifetime, and to determine if a response has expired. |
| 4763 | | In the discussion below, the values can be represented in any form |
| 4764 | | appropriate for arithmetic operations. |
| 4765 | | </t> |
| 4766 | | <t> |
| 4767 | | We use the term "expires_value" to denote the value of the Expires |
| 4768 | | header. We use the term "max_age_value" to denote an appropriate |
| 4769 | | value of the number of seconds carried by the "max-age" directive of |
| 4770 | | the Cache-Control header in a response (see <xref target="modifications.of.the.basic.expiration.mechanism"/>). |
| 4771 | | </t> |
| 4772 | | <t> |
| 4773 | | The max-age directive takes priority over Expires, so if max-age is |
| 4774 | | present in a response, the calculation is simply: |
| 4775 | | </t> |
| 4776 | | <figure><artwork type="code"> |
| 4777 | | freshness_lifetime = max_age_value |
| 4778 | | </artwork></figure> |
| 4779 | | <t> |
| 4780 | | Otherwise, if Expires is present in the response, the calculation is: |
| 4781 | | </t> |
| 4782 | | <figure><artwork type="code"> |
| 4783 | | freshness_lifetime = expires_value - date_value |
| 4784 | | </artwork></figure> |
| 4785 | | <t> |
| 4786 | | Note that neither of these calculations is vulnerable to clock skew, |
| 4787 | | since all of the information comes from the origin server. |
| 4788 | | </t> |
| 4789 | | <t> |
| 4790 | | If none of Expires, Cache-Control: max-age, or Cache-Control: s-maxage |
| 4791 | | (see <xref target="modifications.of.the.basic.expiration.mechanism"/>) appears in the response, and the response |
| 4792 | | does not include other restrictions on caching, the cache &MAY; compute |
| 4793 | | a freshness lifetime using a heuristic. The cache &MUST; attach Warning |
| 4794 | | 113 to any response whose age is more than 24 hours if such warning |
| 4795 | | has not already been added. |
| 4796 | | </t> |
| 4797 | | <t> |
| 4798 | | Also, if the response does have a Last-Modified time, the heuristic |
| 4799 | | expiration value &SHOULD; be no more than some fraction of the interval |
| 4800 | | since that time. A typical setting of this fraction might be 10%. |
| 4801 | | </t> |
| 4802 | | <t> |
| 4803 | | The calculation to determine if a response has expired is quite |
| 4804 | | simple: |
| 4805 | | </t> |
| 4806 | | <figure><artwork type="code"> |
| 4807 | | response_is_fresh = (freshness_lifetime > current_age) |
| 4808 | | </artwork></figure> |
| 4809 | | </section> |
| 4810 | | |
| 4811 | | <section title="Disambiguating Expiration Values" anchor="disambiguating.expiration.values"> |
| 4812 | | <t> |
| 4813 | | Because expiration values are assigned optimistically, it is possible |
| 4814 | | for two caches to contain fresh values for the same resource that are |
| 4815 | | different. |
| 4816 | | </t> |
| 4817 | | <t> |
| 4818 | | If a client performing a retrieval receives a non-first-hand response |
| 4819 | | for a request that was already fresh in its own cache, and the Date |
| 4820 | | header in its existing cache entry is newer than the Date on the new |
| 4821 | | response, then the client &MAY; ignore the response. If so, it &MAY; |
| 4822 | | retry the request with a "Cache-Control: max-age=0" directive (see |
| 4823 | | <xref target="header.cache-control"/>), to force a check with the origin server. |
| 4824 | | </t> |
| 4825 | | <t> |
| 4826 | | If a cache has two fresh responses for the same representation with |
| 4827 | | different validators, it &MUST; use the one with the more recent Date |
| 4828 | | header. This situation might arise because the cache is pooling |
| 4829 | | responses from other caches, or because a client has asked for a |
| 4830 | | reload or a revalidation of an apparently fresh cache entry. |
| 4831 | | </t> |
| 4832 | | </section> |
| 4833 | | |
| 4834 | | <section title="Disambiguating Multiple Responses" anchor="disambiguating.multiple.responses"> |
| 4835 | | <t> |
| 4836 | | Because a client might be receiving responses via multiple paths, so |
| 4837 | | that some responses flow through one set of caches and other |
| 4838 | | responses flow through a different set of caches, a client might |
| 4839 | | receive responses in an order different from that in which the origin |
| 4840 | | server sent them. We would like the client to use the most recently |
| 4841 | | generated response, even if older responses are still apparently |
| 4842 | | fresh. |
| 4843 | | </t> |
| 4844 | | <t> |
| 4845 | | Neither the entity tag nor the expiration value can impose an |
| 4846 | | ordering on responses, since it is possible that a later response |
| 4847 | | intentionally carries an earlier expiration time. The Date values are |
| 4848 | | ordered to a granularity of one second. |
| 4849 | | </t> |
| 4850 | | <t> |
| 4851 | | When a client tries to revalidate a cache entry, and the response it |
| 4852 | | receives contains a Date header that appears to be older than the one |
| 4853 | | for the existing entry, then the client &SHOULD; repeat the request |
| 4854 | | unconditionally, and include |
| 4855 | | </t> |
| 4856 | | <figure><artwork type="example"> |
| 4857 | | Cache-Control: max-age=0 |
| 4858 | | </artwork></figure> |
| 4859 | | <t> |
| 4860 | | to force any intermediate caches to validate their copies directly |
| 4861 | | with the origin server, or |
| 4862 | | </t> |
| 4863 | | <figure><artwork type="example"> |
| 4864 | | Cache-Control: no-cache |
| 4865 | | </artwork></figure> |
| 4866 | | <t> |
| 4867 | | to force any intermediate caches to obtain a new copy from the origin |
| 4868 | | server. |
| 4869 | | </t> |
| 4870 | | <t> |
| 4871 | | If the Date values are equal, then the client &MAY; use either response |
| 4872 | | (or &MAY;, if it is being extremely prudent, request a new response). |
| 4873 | | Servers &MUST-NOT; depend on clients being able to choose |
| 4874 | | deterministically between responses generated during the same second, |
| 4875 | | if their expiration times overlap. |
| 4876 | | </t> |
| 4877 | | </section> |
| 4878 | | </section> |
| 4879 | | |
| 4880 | | <section title="Validation Model" anchor="validation.model"> |
| 4881 | | <t> |
| 4882 | | When a cache has a stale entry that it would like to use as a |
| 4883 | | response to a client's request, it first has to check with the origin |
| 4884 | | server (or possibly an intermediate cache with a fresh response) to |
| 4885 | | see if its cached entry is still usable. We call this "validating" |
| 4886 | | the cache entry. Since we do not want to have to pay the overhead of |
| 4887 | | retransmitting the full response if the cached entry is good, and we |
| 4888 | | do not want to pay the overhead of an extra round trip if the cached |
| 4889 | | entry is invalid, the HTTP/1.1 protocol supports the use of |
| 4890 | | conditional methods. |
| 4891 | | </t> |
| 4892 | | <t> |
| 4893 | | The key protocol features for supporting conditional methods are |
| 4894 | | those concerned with "cache validators." When an origin server |
| 4895 | | generates a full response, it attaches some sort of validator to it, |
| 4896 | | which is kept with the cache entry. When a client (user agent or |
| 4897 | | proxy cache) makes a conditional request for a resource for which it |
| 4898 | | has a cache entry, it includes the associated validator in the |
| 4899 | | request. |
| 4900 | | </t> |
| 4901 | | <t> |
| 4902 | | The server then checks that validator against the current validator |
| 4903 | | for the entity, and, if they match (see <xref target="weak.and.strong.validators"/>), it responds |
| 4904 | | with a special status code (usually, 304 (Not Modified)) and no |
| 4905 | | entity-body. Otherwise, it returns a full response (including |
| 4906 | | entity-body). Thus, we avoid transmitting the full response if the |
| 4907 | | validator matches, and we avoid an extra round trip if it does not |
| 4908 | | match. |
| 4909 | | </t> |
| 4910 | | <t> |
| 4911 | | In HTTP/1.1, a conditional request looks exactly the same as a normal |
| 4912 | | request for the same resource, except that it carries a special |
| 4913 | | header (which includes the validator) that implicitly turns the |
| 4914 | | method (usually, GET) into a conditional. |
| 4915 | | </t> |
| 4916 | | <t> |
| 4917 | | The protocol includes both positive and negative senses of cache-validating |
| 4918 | | conditions. That is, it is possible to request either that |
| 4919 | | a method be performed if and only if a validator matches or if and |
| 4920 | | only if no validators match. |
| 4921 | | <list><t> |
| 4922 | | <x:h>Note:</x:h> a response that lacks a validator may still be cached, and |
| 4923 | | served from cache until it expires, unless this is explicitly |
| 4924 | | prohibited by a cache-control directive. However, a cache cannot |
| 4925 | | do a conditional retrieval if it does not have a validator for the |
| 4926 | | entity, which means it will not be refreshable after it expires. |
| 4927 | | </t></list> |
| 4928 | | </t> |
| 4929 | | |
| 4930 | | <section title="Last-Modified Dates" anchor="last-modified.dates"> |
| 4931 | | <t> |
| 4932 | | The Last-Modified entity-header field value is often used as a cache |
| 4933 | | validator. In simple terms, a cache entry is considered to be valid |
| 4934 | | if the entity has not been modified since the Last-Modified value. |
| 4935 | | </t> |
| 4936 | | </section> |
| 4937 | | |
| 4938 | | <section title="Entity Tag Cache Validators" anchor="entity.tag.cache.validators"> |
| 4939 | | <t> |
| 4940 | | The ETag response-header field value, an entity tag, provides for an |
| 4941 | | "opaque" cache validator. This might allow more reliable validation |
| 4942 | | in situations where it is inconvenient to store modification dates, |
| 4943 | | where the one-second resolution of HTTP date values is not |
| 4944 | | sufficient, or where the origin server wishes to avoid certain |
| 4945 | | paradoxes that might arise from the use of modification dates. |
| 4946 | | </t> |
| 4947 | | <t> |
| 4948 | | Entity Tags are described in <xref target="entity.tags"/>. The headers used with |
| 4949 | | entity tags are described in sections <xref target="header.etag" format="counter"/>, |
| 4950 | | <xref target="header.if-match" format="counter"/>, <xref target="header.if-none-match" format="counter"/> |
| 4951 | | and <xref target="header.vary" format="counter"/>. |
| 4952 | | </t> |
| 4953 | | </section> |
| 4954 | | |
| 4955 | | <section title="Weak and Strong Validators" anchor="weak.and.strong.validators"> |
| 4956 | | <t> |
| 4957 | | Since both origin servers and caches will compare two validators to |
| 4958 | | decide if they represent the same or different entities, one normally |
| 4959 | | would expect that if the entity (the entity-body or any entity-headers) |
| 4960 | | changes in any way, then the associated validator would |
| 4961 | | change as well. If this is true, then we call this validator a |
| 4962 | | "strong validator." |
| 4963 | | </t> |
| 4964 | | <t> |
| 4965 | | However, there might be cases when a server prefers to change the |
| 4966 | | validator only on semantically significant changes, and not when |
| 4967 | | insignificant aspects of the entity change. A validator that does not |
| 4968 | | always change when the resource changes is a "weak validator." |
| 4969 | | </t> |
| 4970 | | <t> |
| 4971 | | Entity tags are normally "strong validators," but the protocol |
| 4972 | | provides a mechanism to tag an entity tag as "weak." One can think of |
| 4973 | | a strong validator as one that changes whenever the bits of an entity |
| 4974 | | changes, while a weak value changes whenever the meaning of an entity |
| 4975 | | changes. Alternatively, one can think of a strong validator as part |
| 4976 | | of an identifier for a specific entity, while a weak validator is |
| 4977 | | part of an identifier for a set of semantically equivalent entities. |
| 4978 | | <list><t> |
| 4979 | | <x:h>Note:</x:h> One example of a strong validator is an integer that is |
| 4980 | | incremented in stable storage every time an entity is changed. |
| 4981 | | </t><t> |
| 4982 | | An entity's modification time, if represented with one-second |
| 4983 | | resolution, could be a weak validator, since it is possible that |
| 4984 | | the resource might be modified twice during a single second. |
| 4985 | | </t><t> |
| 4986 | | Support for weak validators is optional. However, weak validators |
| 4987 | | allow for more efficient caching of equivalent objects; for |
| 4988 | | example, a hit counter on a site is probably good enough if it is |
| 4989 | | updated every few days or weeks, and any value during that period |
| 4990 | | is likely "good enough" to be equivalent. |
| 4991 | | </t></list> |
| 4992 | | </t> |
| 4993 | | <t> |
| 4994 | | A "use" of a validator is either when a client generates a request |
| 4995 | | and includes the validator in a validating header field, or when a |
| 4996 | | server compares two validators. |
| 4997 | | </t> |
| 4998 | | <t> |
| 4999 | | Strong validators are usable in any context. Weak validators are only |
| 5000 | | usable in contexts that do not depend on exact equality of an entity. |
| 5001 | | For example, either kind is usable for a conditional GET of a full |
| 5002 | | entity. However, only a strong validator is usable for a sub-range |
| 5003 | | retrieval, since otherwise the client might end up with an internally |
| 5004 | | inconsistent entity. |
| 5005 | | </t> |
| 5006 | | <t> |
| 5007 | | Clients &MAY; issue simple (non-subrange) GET requests with either weak |
| 5008 | | validators or strong validators. Clients &MUST-NOT; use weak validators |
| 5009 | | in other forms of request. |
| 5010 | | </t> |
| 5011 | | <t> |
| 5012 | | The only function that the HTTP/1.1 protocol defines on validators is |
| 5013 | | comparison. There are two validator comparison functions, depending |
| 5014 | | on whether the comparison context allows the use of weak validators |
| 5015 | | or not: |
| 5016 | | <list style="symbols"> |
| 5017 | | <t>The strong comparison function: in order to be considered equal, |
| 5018 | | both validators &MUST; be identical in every way, and both &MUST-NOT; |
| 5019 | | be weak.</t> |
| 5020 | | <t>The weak comparison function: in order to be considered equal, |
| 5021 | | both validators &MUST; be identical in every way, but either or |
| 5022 | | both of them &MAY; be tagged as "weak" without affecting the |
| 5023 | | result.</t> |
| 5024 | | </list> |
| 5025 | | </t> |
| 5026 | | <t> |
| 5027 | | An entity tag is strong unless it is explicitly tagged as weak. |
| 5028 | | <xref target="entity.tags"/> gives the syntax for entity tags. |
| 5029 | | </t> |
| 5030 | | <t> |
| 5031 | | A Last-Modified time, when used as a validator in a request, is |
| 5032 | | implicitly weak unless it is possible to deduce that it is strong, |
| 5033 | | using the following rules: |
| 5034 | | <list style="symbols"> |
| 5035 | | <t>The validator is being compared by an origin server to the |
| 5036 | | actual current validator for the entity and,</t> |
| 5037 | | <t>That origin server reliably knows that the associated entity did |
| 5038 | | not change twice during the second covered by the presented |
| 5039 | | validator.</t> |
| 5040 | | </list> |
| 5041 | | </t> |
| 5042 | | <t> |
| 5043 | | or |
| 5044 | | <list style="symbols"> |
| 5045 | | <t>The validator is about to be used by a client in an If-Modified-Since |
| 5046 | | or If-Unmodified-Since header, because the client |
| 5047 | | has a cache entry for the associated entity, and</t> |
| 5048 | | <t>That cache entry includes a Date value, which gives the time |
| 5049 | | when the origin server sent the original response, and</t> |
| 5050 | | <t>The presented Last-Modified time is at least 60 seconds before |
| 5051 | | the Date value.</t> |
| 5052 | | </list> |
| 5053 | | </t> |
| 5054 | | <t> |
| 5055 | | or |
| 5056 | | <list style="symbols"> |
| 5057 | | <t>The validator is being compared by an intermediate cache to the |
| 5058 | | validator stored in its cache entry for the entity, and</t> |
| 5059 | | <t>That cache entry includes a Date value, which gives the time |
| 5060 | | when the origin server sent the original response, and</t> |
| 5061 | | <t>The presented Last-Modified time is at least 60 seconds before |
| 5062 | | the Date value.</t> |
| 5063 | | </list> |
| 5064 | | </t> |
| 5065 | | <t> |
| 5066 | | This method relies on the fact that if two different responses were |
| 5067 | | sent by the origin server during the same second, but both had the |
| 5068 | | same Last-Modified time, then at least one of those responses would |
| 5069 | | have a Date value equal to its Last-Modified time. The arbitrary 60-second |
| 5070 | | limit guards against the possibility that the Date and Last-Modified |
| 5071 | | values are generated from different clocks, or at somewhat |
| 5072 | | different times during the preparation of the response. An |
| 5073 | | implementation &MAY; use a value larger than 60 seconds, if it is |
| 5074 | | believed that 60 seconds is too short. |
| 5075 | | </t> |
| 5076 | | <t> |
| 5077 | | If a client wishes to perform a sub-range retrieval on a value for |
| 5078 | | which it has only a Last-Modified time and no opaque validator, it |
| 5079 | | &MAY; do this only if the Last-Modified time is strong in the sense |
| 5080 | | described here. |
| 5081 | | </t> |
| 5082 | | <t> |
| 5083 | | A cache or origin server receiving a conditional request, other than |
| 5084 | | a full-body GET request, &MUST; use the strong comparison function to |
| 5085 | | evaluate the condition. |
| 5086 | | </t> |
| 5087 | | <t> |
| 5088 | | These rules allow HTTP/1.1 caches and clients to safely perform sub-range |
| 5089 | | retrievals on values that have been obtained from HTTP/1.0 |
| 5090 | | servers. |
| 5091 | | </t> |
| 5092 | | </section> |
| 5093 | | |
| 5094 | | <section title="Rules for When to Use Entity Tags and Last-Modified Dates" anchor="rules.for.when.to.use.entity.tags.and.last-modified.dates"> |
| 5095 | | <t> |
| 5096 | | We adopt a set of rules and recommendations for origin servers, |
| 5097 | | clients, and caches regarding when various validator types ought to |
| 5098 | | be used, and for what purposes. |
| 5099 | | </t> |
| 5100 | | <t> |
| 5101 | | HTTP/1.1 origin servers: |
| 5102 | | <list style="symbols"> |
| 5103 | | <t>&SHOULD; send an entity tag validator unless it is not feasible to |
| 5104 | | generate one.</t> |
| 5105 | | |
| 5106 | | <t>&MAY; send a weak entity tag instead of a strong entity tag, if |
| 5107 | | performance considerations support the use of weak entity tags, |
| 5108 | | or if it is unfeasible to send a strong entity tag.</t> |
| 5109 | | |
| 5110 | | <t>&SHOULD; send a Last-Modified value if it is feasible to send one, |
| 5111 | | unless the risk of a breakdown in semantic transparency that |
| 5112 | | could result from using this date in an If-Modified-Since header |
| 5113 | | would lead to serious problems.</t> |
| 5114 | | </list> |
| 5115 | | </t> |
| 5116 | | <t> |
| 5117 | | In other words, the preferred behavior for an HTTP/1.1 origin server |
| 5118 | | is to send both a strong entity tag and a Last-Modified value. |
| 5119 | | </t> |
| 5120 | | <t> |
| 5121 | | In order to be legal, a strong entity tag &MUST; change whenever the |
| 5122 | | associated entity value changes in any way. A weak entity tag &SHOULD; |
| 5123 | | change whenever the associated entity changes in a semantically |
| 5124 | | significant way. |
| 5125 | | <list><t> |
| 5126 | | <x:h>Note:</x:h> in order to provide semantically transparent caching, an |
| 5127 | | origin server must avoid reusing a specific strong entity tag |
| 5128 | | value for two different entities, or reusing a specific weak |
| 5129 | | entity tag value for two semantically different entities. Cache |
| 5130 | | entries might persist for arbitrarily long periods, regardless of |
| 5131 | | expiration times, so it might be inappropriate to expect that a |
| 5132 | | cache will never again attempt to validate an entry using a |
| 5133 | | validator that it obtained at some point in the past. |
| 5134 | | </t></list> |
| 5135 | | </t> |
| 5136 | | <t> |
| 5137 | | HTTP/1.1 clients: |
| 5138 | | <list style="symbols"> |
| 5139 | | <t>If an entity tag has been provided by the origin server, &MUST; |
| 5140 | | use that entity tag in any cache-conditional request (using If-Match |
| 5141 | | or If-None-Match).</t> |
| 5142 | | |
| 5143 | | <t>If only a Last-Modified value has been provided by the origin |
| 5144 | | server, &SHOULD; use that value in non-subrange cache-conditional |
| 5145 | | requests (using If-Modified-Since).</t> |
| 5146 | | |
| 5147 | | <t>If only a Last-Modified value has been provided by an HTTP/1.0 |
| 5148 | | origin server, &MAY; use that value in subrange cache-conditional |
| 5149 | | requests (using If-Unmodified-Since:). The user agent &SHOULD; |
| 5150 | | provide a way to disable this, in case of difficulty.</t> |
| 5151 | | |
| 5152 | | <t>If both an entity tag and a Last-Modified value have been |
| 5153 | | provided by the origin server, &SHOULD; use both validators in |
| 5154 | | cache-conditional requests. This allows both HTTP/1.0 and |
| 5155 | | HTTP/1.1 caches to respond appropriately.</t> |
| 5156 | | </list> |
| 5157 | | </t> |
| 5158 | | <t> |
| 5159 | | An HTTP/1.1 origin server, upon receiving a conditional request that |
| 5160 | | includes both a Last-Modified date (e.g., in an If-Modified-Since or |
| 5161 | | If-Unmodified-Since header field) and one or more entity tags (e.g., |
| 5162 | | in an If-Match, If-None-Match, or If-Range header field) as cache |
| 5163 | | validators, &MUST-NOT; return a response status of 304 (Not Modified) |
| 5164 | | unless doing so is consistent with all of the conditional header |
| 5165 | | fields in the request. |
| 5166 | | </t> |
| 5167 | | <t> |
| 5168 | | An HTTP/1.1 caching proxy, upon receiving a conditional request that |
| 5169 | | includes both a Last-Modified date and one or more entity tags as |
| 5170 | | cache validators, &MUST-NOT; return a locally cached response to the |
| 5171 | | client unless that cached response is consistent with all of the |
| 5172 | | conditional header fields in the request. |
| 5173 | | <list><t> |
| 5174 | | <x:h>Note:</x:h> The general principle behind these rules is that HTTP/1.1 |
| 5175 | | servers and clients should transmit as much non-redundant |
| 5176 | | information as is available in their responses and requests. |
| 5177 | | HTTP/1.1 systems receiving this information will make the most |
| 5178 | | conservative assumptions about the validators they receive. |
| 5179 | | </t><t> |
| 5180 | | HTTP/1.0 clients and caches will ignore entity tags. Generally, |
| 5181 | | last-modified values received or used by these systems will |
| 5182 | | support transparent and efficient caching, and so HTTP/1.1 origin |
| 5183 | | servers should provide Last-Modified values. In those rare cases |
| 5184 | | where the use of a Last-Modified value as a validator by an |
| 5185 | | HTTP/1.0 system could result in a serious problem, then HTTP/1.1 |
| 5186 | | origin servers should not provide one. |
| 5187 | | </t></list> |
| 5188 | | </t> |
| 5189 | | </section> |
| 5190 | | |
| 5191 | | <section title="Non-validating Conditionals" anchor="non-validating.conditionals"> |
| 5192 | | <t> |
| 5193 | | The principle behind entity tags is that only the service author |
| 5194 | | knows the semantics of a resource well enough to select an |
| 5195 | | appropriate cache validation mechanism, and the specification of any |
| 5196 | | validator comparison function more complex than byte-equality would |
| 5197 | | open up a can of worms. Thus, comparisons of any other headers |
| 5198 | | (except Last-Modified, for compatibility with HTTP/1.0) are never |
| 5199 | | used for purposes of validating a cache entry. |
| 5200 | | </t> |
| 5201 | | </section> |
| 5202 | | </section> |
| 5203 | | |
| 5204 | | <section title="Response Cacheability" anchor="response.cacheability"> |
| 5205 | | <t> |
| 5206 | | Unless specifically constrained by a cache-control (<xref target="header.cache-control"/>) |
| 5207 | | directive, a caching system &MAY; always store a successful response |
| 5208 | | (see <xref target="errors.or.incomplete.response.cache.behavior"/>) as a cache entry, &MAY; return it without validation |
| 5209 | | if it is fresh, and &MAY; return it after successful validation. If |
| 5210 | | there is neither a cache validator nor an explicit expiration time |
| 5211 | | associated with a response, we do not expect it to be cached, but |
| 5212 | | certain caches &MAY; violate this expectation (for example, when little |
| 5213 | | or no network connectivity is available). A client can usually detect |
| 5214 | | that such a response was taken from a cache by comparing the Date |
| 5215 | | header to the current time. |
| 5216 | | <list><t> |
| 5217 | | <x:h>Note:</x:h> some HTTP/1.0 caches are known to violate this expectation |
| 5218 | | without providing any Warning. |
| 5219 | | </t></list> |
| 5220 | | </t> |
| 5221 | | <t> |
| 5222 | | However, in some cases it might be inappropriate for a cache to |
| 5223 | | retain an entity, or to return it in response to a subsequent |
| 5224 | | request. This might be because absolute semantic transparency is |
| 5225 | | deemed necessary by the service author, or because of security or |
| 5226 | | privacy considerations. Certain cache-control directives are |
| 5227 | | therefore provided so that the server can indicate that certain |
| 5228 | | resource entities, or portions thereof, are not to be cached |
| 5229 | | regardless of other considerations. |
| 5230 | | </t> |
| 5231 | | <t> |
| 5232 | | Note that <xref target="header.authorization"/> normally prevents a shared cache from saving |
| 5233 | | and returning a response to a previous request if that request |
| 5234 | | included an Authorization header. |
| 5235 | | </t> |
| 5236 | | <t> |
| 5237 | | A response received with a status code of 200, 203, 206, 300, 301 or |
| 5238 | | 410 &MAY; be stored by a cache and used in reply to a subsequent |
| 5239 | | request, subject to the expiration mechanism, unless a cache-control |
| 5240 | | directive prohibits caching. However, a cache that does not support |
| 5241 | | the Range and Content-Range headers &MUST-NOT; cache 206 (Partial |
| 5242 | | Content) responses. |
| 5243 | | </t> |
| 5244 | | <t> |
| 5245 | | A response received with any other status code (e.g. status codes 302 |
| 5246 | | and 307) &MUST-NOT; be returned in a reply to a subsequent request |
| 5247 | | unless there are cache-control directives or another header(s) that |
| 5248 | | explicitly allow it. For example, these include the following: an |
| 5249 | | Expires header (<xref target="header.expires"/>); a "max-age", "s-maxage", "must-revalidate", |
| 5250 | | "proxy-revalidate", "public" or "private" cache-control |
| 5251 | | directive (<xref target="header.cache-control"/>). |
| 5252 | | </t> |
| 5253 | | </section> |
| 5254 | | |
| 5255 | | <section title="Constructing Responses From Caches" anchor="constructing.responses.from.caches"> |
| 5256 | | <t> |
| 5257 | | The purpose of an HTTP cache is to store information received in |
| 5258 | | response to requests for use in responding to future requests. In |
| 5259 | | many cases, a cache simply returns the appropriate parts of a |
| 5260 | | response to the requester. However, if the cache holds a cache entry |
| 5261 | | based on a previous response, it might have to combine parts of a new |
| 5262 | | response with what is held in the cache entry. |
| 5263 | | </t> |
| 5264 | | |
| 5265 | | <section title="End-to-end and Hop-by-hop Headers" anchor="end-to-end.and.hop-by-hop.headers"> |
| 5266 | | <t> |
| 5267 | | For the purpose of defining the behavior of caches and non-caching |
| 5268 | | proxies, we divide HTTP headers into two categories: |
| 5269 | | <list style="symbols"> |
| 5270 | | <t>End-to-end headers, which are transmitted to the ultimate |
| 5271 | | recipient of a request or response. End-to-end headers in |
| 5272 | | responses &MUST; be stored as part of a cache entry and &MUST; be |
| 5273 | | transmitted in any response formed from a cache entry.</t> |
| 5274 | | |
| 5275 | | <t>Hop-by-hop headers, which are meaningful only for a single |
| 5276 | | transport-level connection, and are not stored by caches or |
| 5277 | | forwarded by proxies.</t> |
| 5278 | | </list> |
| 5279 | | </t> |
| 5280 | | <t> |
| 5281 | | The following HTTP/1.1 headers are hop-by-hop headers: |
| 5282 | | <list style="symbols"> |
| 5283 | | <t>Connection</t> |
| 5284 | | <t>Keep-Alive</t> |
| 5285 | | <t>Proxy-Authenticate</t> |
| 5286 | | <t>Proxy-Authorization</t> |
| 5287 | | <t>TE</t> |
| 5288 | | <t>Trailers</t> |
| 5289 | | <t>Transfer-Encoding</t> |
| 5290 | | <t>Upgrade</t> |
| 5291 | | </list> |
| 5292 | | </t> |
| 5293 | | <t> |
| 5294 | | All other headers defined by HTTP/1.1 are end-to-end headers. |
| 5295 | | </t> |
| 5296 | | <t> |
| 5297 | | Other hop-by-hop headers &MUST; be listed in a Connection header, |
| 5298 | | (<xref target="header.connection"/>) to be introduced into HTTP/1.1 (or later). |
| 5299 | | </t> |
| 5300 | | </section> |
| 5301 | | |
| 5302 | | <section title="Non-modifiable Headers" anchor="non-modifiable.headers"> |
| 5303 | | <t> |
| 5304 | | Some features of the HTTP/1.1 protocol, such as Digest |
| 5305 | | Authentication, depend on the value of certain end-to-end headers. A |
| 5306 | | transparent proxy &SHOULD-NOT; modify an end-to-end header unless the |
| 5307 | | definition of that header requires or specifically allows that. |
| 5308 | | </t> |
| 5309 | | <t> |
| 5310 | | A transparent proxy &MUST-NOT; modify any of the following fields in a |
| 5311 | | request or response, and it &MUST-NOT; add any of these fields if not |
| 5312 | | already present: |
| 5313 | | <list style="symbols"> |
| 5314 | | <t>Content-Location</t> |
| 5315 | | <t>Content-MD5</t> |
| 5316 | | <t>ETag</t> |
| 5317 | | <t>Last-Modified</t> |
| 5318 | | </list> |
| 5319 | | </t> |
| 5320 | | <t> |
| 5321 | | A transparent proxy &MUST-NOT; modify any of the following fields in a |
| 5322 | | response: |
| 5323 | | <list style="symbols"> |
| 5324 | | <t>Expires</t> |
| 5325 | | </list> |
| 5326 | | </t> |
| 5327 | | <t> |
| 5328 | | but it &MAY; add any of these fields if not already present. If an |
| 5329 | | Expires header is added, it &MUST; be given a field-value identical to |
| 5330 | | that of the Date header in that response. |
| 5331 | | </t> |
| 5332 | | <t> |
| 5333 | | A proxy &MUST-NOT; modify or add any of the following fields in a |
| 5334 | | message that contains the no-transform cache-control directive, or in |
| 5335 | | any request: |
| 5336 | | <list style="symbols"> |
| 5337 | | <t>Content-Encoding</t> |
| 5338 | | <t>Content-Range</t> |
| 5339 | | <t>Content-Type</t> |
| 5340 | | </list> |
| 5341 | | </t> |
| 5342 | | <t> |
| 5343 | | A non-transparent proxy &MAY; modify or add these fields to a message |
| 5344 | | that does not include no-transform, but if it does so, it &MUST; add a |
| 5345 | | Warning 214 (Transformation applied) if one does not already appear |
| 5346 | | in the message (see <xref target="header.warning"/>). |
| 5347 | | <list><t> |
| 5348 | | Warning: unnecessary modification of end-to-end headers might |
| 5349 | | cause authentication failures if stronger authentication |
| 5350 | | mechanisms are introduced in later versions of HTTP. Such |
| 5351 | | authentication mechanisms &MAY; rely on the values of header fields |
| 5352 | | not listed here. |
| 5353 | | </t></list> |
| 5354 | | </t> |
| 5355 | | <t> |
| 5356 | | The Content-Length field of a request or response is added or deleted |
| 5357 | | according to the rules in <xref target="message.length"/>. A transparent proxy &MUST; |
| 5358 | | preserve the entity-length (<xref target="entity.length"/>) of the entity-body, |
| 5359 | | although it &MAY; change the transfer-length (<xref target="message.length"/>). |
| 5360 | | </t> |
| 5361 | | </section> |
| 5362 | | |
| 5363 | | <section title="Combining Headers" anchor="combining.headers"> |
| 5364 | | <t> |
| 5365 | | When a cache makes a validating request to a server, and the server |
| 5366 | | provides a 304 (Not Modified) response or a 206 (Partial Content) |
| 5367 | | response, the cache then constructs a response to send to the |
| 5368 | | requesting client. |
| 5369 | | </t> |
| 5370 | | <t> |
| 5371 | | If the status code is 304 (Not Modified), the cache uses the entity-body |
| 5372 | | stored in the cache entry as the entity-body of this outgoing |
| 5373 | | response. If the status code is 206 (Partial Content) and the ETag or |
| 5374 | | Last-Modified headers match exactly, the cache &MAY; combine the |
| 5375 | | contents stored in the cache entry with the new contents received in |
| 5376 | | the response and use the result as the entity-body of this outgoing |
| 5377 | | response, (see <xref target="combining.byte.ranges" format="counter"/>). |
| 5378 | | </t> |
| 5379 | | <t> |
| 5380 | | The end-to-end headers stored in the cache entry are used for the |
| 5381 | | constructed response, except that |
| 5382 | | <list style="symbols"> |
| 5383 | | <t>any stored Warning headers with warn-code 1xx (see <xref target="header.warning"/>) |
| 5384 | | &MUST; be deleted from the cache entry and the forwarded response.</t> |
| 5385 | | <t>any stored Warning headers with warn-code 2xx &MUST; be retained |
| 5386 | | in the cache entry and the forwarded response.</t> |
| 5387 | | <t>any end-to-end headers provided in the 304 or 206 response &MUST; |
| 5388 | | replace the corresponding headers from the cache entry.</t> |
| 5389 | | </list> |
| 5390 | | </t> |
| 5391 | | <t> |
| 5392 | | Unless the cache decides to remove the cache entry, it &MUST; also |
| 5393 | | replace the end-to-end headers stored with the cache entry with |
| 5394 | | corresponding headers received in the incoming response, except for |
| 5395 | | Warning headers as described immediately above. If a header field-name |
| 5396 | | in the incoming response matches more than one header in the |
| 5397 | | cache entry, all such old headers &MUST; be replaced. |
| 5398 | | </t> |
| 5399 | | <t> |
| 5400 | | In other words, the set of end-to-end headers received in the |
| 5401 | | incoming response overrides all corresponding end-to-end headers |
| 5402 | | stored with the cache entry (except for stored Warning headers with |
| 5403 | | warn-code 1xx, which are deleted even if not overridden). |
| 5404 | | <list><t> |
| 5405 | | <x:h>Note:</x:h> this rule allows an origin server to use a 304 (Not |
| 5406 | | Modified) or a 206 (Partial Content) response to update any header |
| 5407 | | associated with a previous response for the same entity or sub-ranges |
| 5408 | | thereof, although it might not always be meaningful or |
| 5409 | | correct to do so. This rule does not allow an origin server to use |
| 5410 | | a 304 (Not Modified) or a 206 (Partial Content) response to |
| 5411 | | entirely delete a header that it had provided with a previous |
| 5412 | | response. |
| 5413 | | </t></list> |
| 5414 | | </t> |
| 5415 | | </section> |
| 5416 | | |
| 5417 | | <section title="Combining Byte Ranges" anchor="combining.byte.ranges"> |
| 5418 | | <t> |
| 5419 | | A response might transfer only a subrange of the bytes of an entity-body, |
| 5420 | | either because the request included one or more Range |
| 5421 | | specifications, or because a connection was broken prematurely. After |
| 5422 | | several such transfers, a cache might have received several ranges of |
| 5423 | | the same entity-body. |
| 5424 | | </t> |
| 5425 | | <t> |
| 5426 | | If a cache has a stored non-empty set of subranges for an entity, and |
| 5427 | | an incoming response transfers another subrange, the cache &MAY; |
| 5428 | | combine the new subrange with the existing set if both the following |
| 5429 | | conditions are met: |
| 5430 | | <list style="symbols"> |
| 5431 | | <t>Both the incoming response and the cache entry have a cache |
| 5432 | | validator.</t> |
| 5433 | | <t>The two cache validators match using the strong comparison |
| 5434 | | function (see <xref target="weak.and.strong.validators"/>).</t> |
| 5435 | | </list> |
| 5436 | | </t> |
| 5437 | | <t> |
| 5438 | | If either requirement is not met, the cache &MUST; use only the most |
| 5439 | | recent partial response (based on the Date values transmitted with |
| 5440 | | every response, and using the incoming response if these values are |
| 5441 | | equal or missing), and &MUST; discard the other partial information. |
| 5442 | | </t> |
| 5443 | | </section> |
| 5444 | | </section> |
| 5445 | | |
| 5446 | | <section title="Caching Negotiated Responses" anchor="caching.negotiated.responses"> |
| 5447 | | <t> |
| 5448 | | Use of server-driven content negotiation (<xref target="server-driven.negotiation"/>), as indicated |
| 5449 | | by the presence of a Vary header field in a response, alters the |
| 5450 | | conditions and procedure by which a cache can use the response for |
| 5451 | | subsequent requests. See <xref target="header.vary"/> for use of the Vary header |
| 5452 | | field by servers. |
| 5453 | | </t> |
| 5454 | | <t> |
| 5455 | | A server &SHOULD; use the Vary header field to inform a cache of what |
| 5456 | | request-header fields were used to select among multiple |
| 5457 | | representations of a cacheable response subject to server-driven |
| 5458 | | negotiation. The set of header fields named by the Vary field value |
| 5459 | | is known as the "selecting" request-headers. |
| 5460 | | </t> |
| 5461 | | <t> |
| 5462 | | When the cache receives a subsequent request whose Request-URI |
| 5463 | | specifies one or more cache entries including a Vary header field, |
| 5464 | | the cache &MUST-NOT; use such a cache entry to construct a response to |
| 5465 | | the new request unless all of the selecting request-headers present |
| 5466 | | in the new request match the corresponding stored request-headers in |
| 5467 | | the original request. |
| 5468 | | </t> |
| 5469 | | <t> |
| 5470 | | The selecting request-headers from two requests are defined to match |
| 5471 | | if and only if the selecting request-headers in the first request can |
| 5472 | | be transformed to the selecting request-headers in the second request |
| 5473 | | by adding or removing linear white space (LWS) at places where this |
| 5474 | | is allowed by the corresponding BNF, and/or combining multiple |
| 5475 | | message-header fields with the same field name following the rules |
| 5476 | | about message headers in <xref target="message.headers"/>. |
| 5477 | | </t> |
| 5478 | | <t> |
| 5479 | | A Vary header field-value of "*" always fails to match and subsequent |
| 5480 | | requests on that resource can only be properly interpreted by the |
| 5481 | | origin server. |
| 5482 | | </t> |
| 5483 | | <t> |
| 5484 | | If the selecting request header fields for the cached entry do not |
| 5485 | | match the selecting request header fields of the new request, then |
| 5486 | | the cache &MUST-NOT; use a cached entry to satisfy the request unless |
| 5487 | | it first relays the new request to the origin server in a conditional |
| 5488 | | request and the server responds with 304 (Not Modified), including an |
| 5489 | | entity tag or Content-Location that indicates the entity to be used. |
| 5490 | | </t> |
| 5491 | | <t> |
| 5492 | | If an entity tag was assigned to a cached representation, the |
| 5493 | | forwarded request &SHOULD; be conditional and include the entity tags |
| 5494 | | in an If-None-Match header field from all its cache entries for the |
| 5495 | | resource. This conveys to the server the set of entities currently |
| 5496 | | held by the cache, so that if any one of these entities matches the |
| 5497 | | requested entity, the server can use the ETag header field in its 304 |
| 5498 | | (Not Modified) response to tell the cache which entry is appropriate. |
| 5499 | | If the entity-tag of the new response matches that of an existing |
| 5500 | | entry, the new response &SHOULD; be used to update the header fields of |
| 5501 | | the existing entry, and the result &MUST; be returned to the client. |
| 5502 | | </t> |
| 5503 | | <t> |
| 5504 | | If any of the existing cache entries contains only partial content |
| 5505 | | for the associated entity, its entity-tag &SHOULD-NOT; be included in |
| 5506 | | the If-None-Match header field unless the request is for a range that |
| 5507 | | would be fully satisfied by that entry. |
| 5508 | | </t> |
| 5509 | | <t> |
| 5510 | | If a cache receives a successful response whose Content-Location |
| 5511 | | field matches that of an existing cache entry for the same Request-URI, |
| 5512 | | whose entity-tag differs from that of the existing entry, and |
| 5513 | | whose Date is more recent than that of the existing entry, the |
| 5514 | | existing entry &SHOULD-NOT; be returned in response to future requests |
| 5515 | | and &SHOULD; be deleted from the cache. |
| 5516 | | </t> |
| 5517 | | </section> |
| 5518 | | |
| 5519 | | <section title="Shared and Non-Shared Caches" anchor="shared.and.non-shared.caches"> |
| 5520 | | <t> |
| 5521 | | For reasons of security and privacy, it is necessary to make a |
| 5522 | | distinction between "shared" and "non-shared" caches. A non-shared |
| 5523 | | cache is one that is accessible only to a single user. Accessibility |
| 5524 | | in this case &SHOULD; be enforced by appropriate security mechanisms. |
| 5525 | | All other caches are considered to be "shared." Other sections of |
| 5526 | | this specification place certain constraints on the operation of |
| 5527 | | shared caches in order to prevent loss of privacy or failure of |
| 5528 | | access controls. |
| 5529 | | </t> |
| 5530 | | </section> |
| 5531 | | |
| 5532 | | <section title="Errors or Incomplete Response Cache Behavior" anchor="errors.or.incomplete.response.cache.behavior"> |
| 5533 | | <t> |
| 5534 | | A cache that receives an incomplete response (for example, with fewer |
| 5535 | | bytes of data than specified in a Content-Length header) &MAY; store |
| 5536 | | the response. However, the cache &MUST; treat this as a partial |
| 5537 | | response. Partial responses &MAY; be combined as described in <xref target="combining.byte.ranges"/>; |
| 5538 | | the result might be a full response or might still be |
| 5539 | | partial. A cache &MUST-NOT; return a partial response to a client |
| 5540 | | without explicitly marking it as such, using the 206 (Partial |
| 5541 | | Content) status code. A cache &MUST-NOT; return a partial response |
| 5542 | | using a status code of 200 (OK). |
| 5543 | | </t> |
| 5544 | | <t> |
| 5545 | | If a cache receives a 5xx response while attempting to revalidate an |
| 5546 | | entry, it &MAY; either forward this response to the requesting client, |
| 5547 | | or act as if the server failed to respond. In the latter case, it &MAY; |
| 5548 | | return a previously received response unless the cached entry |
| 5549 | | includes the "must-revalidate" cache-control directive (see <xref target="header.cache-control"/>). |
| 5550 | | </t> |
| 5551 | | </section> |
| 5552 | | |
| 5553 | | <section title="Side Effects of GET and HEAD" anchor="side.effects.of.get.and.head"> |
| 5554 | | <t> |
| 5555 | | Unless the origin server explicitly prohibits the caching of their |
| 5556 | | responses, the application of GET and HEAD methods to any resources |
| 5557 | | &SHOULD-NOT; have side effects that would lead to erroneous behavior if |
| 5558 | | these responses are taken from a cache. They &MAY; still have side |
| 5559 | | effects, but a cache is not required to consider such side effects in |
| 5560 | | its caching decisions. Caches are always expected to observe an |
| 5561 | | origin server's explicit restrictions on caching. |
| 5562 | | </t> |
| 5563 | | <t> |
| 5564 | | We note one exception to this rule: since some applications have |
| 5565 | | traditionally used GETs and HEADs with query URLs (those containing a |
| 5566 | | "?" in the rel_path part) to perform operations with significant side |
| 5567 | | effects, caches &MUST-NOT; treat responses to such URIs as fresh unless |
| 5568 | | the server provides an explicit expiration time. This specifically |
| 5569 | | means that responses from HTTP/1.0 servers for such URIs &SHOULD-NOT; |
| 5570 | | be taken from a cache. See <xref target="safe.methods"/> for related information. |
| 5571 | | </t> |
| 5572 | | </section> |
| 5573 | | |
| 5574 | | <section title="Invalidation After Updates or Deletions" anchor="invalidation.after.updates.or.deletions"> |
| 5575 | | <t> |
| 5576 | | The effect of certain methods performed on a resource at the origin |
| 5577 | | server might cause one or more existing cache entries to become non-transparently |
| 5578 | | invalid. That is, although they might continue to be |
| 5579 | | "fresh," they do not accurately reflect what the origin server would |
| 5580 | | return for a new request on that resource. |
| 5581 | | </t> |
| 5582 | | <t> |
| 5583 | | There is no way for the HTTP protocol to guarantee that all such |
| 5584 | | cache entries are marked invalid. For example, the request that |
| 5585 | | caused the change at the origin server might not have gone through |
| 5586 | | the proxy where a cache entry is stored. However, several rules help |
| 5587 | | reduce the likelihood of erroneous behavior. |
| 5588 | | </t> |
| 5589 | | <t> |
| 5590 | | In this section, the phrase "invalidate an entity" means that the |
| 5591 | | cache will either remove all instances of that entity from its |
| 5592 | | storage, or will mark these as "invalid" and in need of a mandatory |
| 5593 | | revalidation before they can be returned in response to a subsequent |
| 5594 | | request. |
| 5595 | | </t> |
| 5596 | | <t> |
| 5597 | | Some HTTP methods &MUST; cause a cache to invalidate an entity. This is |
| 5598 | | either the entity referred to by the Request-URI, or by the Location |
| 5599 | | or Content-Location headers (if present). These methods are: |
| 5600 | | <list style="symbols"> |
| 5601 | | <t>PUT</t> |
| 5602 | | <t>DELETE</t> |
| 5603 | | <t>POST</t> |
| 5604 | | </list> |
| 5605 | | </t> |
| 5606 | | <t> |
| 5607 | | In order to prevent denial of service attacks, an invalidation based |
| 5608 | | on the URI in a Location or Content-Location header &MUST; only be |
| 5609 | | performed if the host part is the same as in the Request-URI. |
| 5610 | | </t> |
| 5611 | | <t> |
| 5612 | | A cache that passes through requests for methods it does not |
| 5613 | | understand &SHOULD; invalidate any entities referred to by the |
| 5614 | | Request-URI. |
| 5615 | | </t> |
| 5616 | | </section> |
| 5617 | | |
| 5618 | | <section title="Write-Through Mandatory" anchor="write-through.mandatory"> |
| 5619 | | <t> |
| 5620 | | All methods that might be expected to cause modifications to the |
| 5621 | | origin server's resources &MUST; be written through to the origin |
| 5622 | | server. This currently includes all methods except for GET and HEAD. |
| 5623 | | A cache &MUST-NOT; reply to such a request from a client before having |
| 5624 | | transmitted the request to the inbound server, and having received a |
| 5625 | | corresponding response from the inbound server. This does not prevent |
| 5626 | | a proxy cache from sending a 100 (Continue) response before the |
| 5627 | | inbound server has sent its final reply. |
| 5628 | | </t> |
| 5629 | | <t> |
| 5630 | | The alternative (known as "write-back" or "copy-back" caching) is not |
| 5631 | | allowed in HTTP/1.1, due to the difficulty of providing consistent |
| 5632 | | updates and the problems arising from server, cache, or network |
| 5633 | | failure prior to write-back. |
| 5634 | | </t> |
| 5635 | | </section> |
| 5636 | | |
| 5637 | | <section title="Cache Replacement" anchor="cache.replacement"> |
| 5638 | | <t> |
| 5639 | | If a new cacheable (see sections <xref target="what.may.be.stored.by.caches" format="counter"/>, |
| 5640 | | <xref target="disambiguating.expiration.values" format="counter"/>, |
| 5641 | | <xref target="disambiguating.multiple.responses" format="counter"/> |
| 5642 | | and <xref target="errors.or.incomplete.response.cache.behavior" format="counter"/>) |
| 5643 | | response is received from a resource while any existing responses for |
| 5644 | | the same resource are cached, the cache &SHOULD; use the new response |
| 5645 | | to reply to the current request. It &MAY; insert it into cache storage |
| 5646 | | and &MAY;, if it meets all other requirements, use it to respond to any |
| 5647 | | future requests that would previously have caused the old response to |
| 5648 | | be returned. If it inserts the new response into cache storage the |
| 5649 | | rules in <xref target="combining.headers"/> apply. |
| 5650 | | <list><t> |
| 5651 | | <x:h>Note:</x:h> a new response that has an older Date header value than |
| 5652 | | existing cached responses is not cacheable. |
| 5653 | | </t></list> |
| 5654 | | </t> |
| 5655 | | </section> |
| 5656 | | |
| 5657 | | <section title="History Lists" anchor="history.lists"> |
| 5658 | | <t> |
| 5659 | | User agents often have history mechanisms, such as "Back" buttons and |
| 5660 | | history lists, which can be used to redisplay an entity retrieved |
| 5661 | | earlier in a session. |
| 5662 | | </t> |
| 5663 | | <t> |
| 5664 | | History mechanisms and caches are different. In particular history |
| 5665 | | mechanisms &SHOULD-NOT; try to show a semantically transparent view of |
| 5666 | | the current state of a resource. Rather, a history mechanism is meant |
| 5667 | | to show exactly what the user saw at the time when the resource was |
| 5668 | | retrieved. |
| 5669 | | </t> |
| 5670 | | <t> |
| 5671 | | By default, an expiration time does not apply to history mechanisms. |
| 5672 | | If the entity is still in storage, a history mechanism &SHOULD; display |
| 5673 | | it even if the entity has expired, unless the user has specifically |
| 5674 | | configured the agent to refresh expired history documents. |
| 5675 | | </t> |
| 5676 | | <t> |
| 5677 | | This is not to be construed to prohibit the history mechanism from |
| 5678 | | telling the user that a view might be stale. |
| 5679 | | <list><t> |
| 5680 | | <x:h>Note:</x:h> if history list mechanisms unnecessarily prevent users from |
| 5681 | | viewing stale resources, this will tend to force service authors |
| 5682 | | to avoid using HTTP expiration controls and cache controls when |
| 5683 | | they would otherwise like to. Service authors may consider it |
| 5684 | | important that users not be presented with error messages or |
| 5685 | | warning messages when they use navigation controls (such as BACK) |
| 5686 | | to view previously fetched resources. Even though sometimes such |
| 5687 | | resources ought not to cached, or ought to expire quickly, user |
| 5688 | | interface considerations may force service authors to resort to |
| 5689 | | other means of preventing caching (e.g. "once-only" URLs) in order |
| 5690 | | not to suffer the effects of improperly functioning history |
| 5691 | | mechanisms. |
| 5692 | | </t></list> |
| 5693 | | </t> |
| 5694 | | </section> |
| 5695 | | </section> |
| 5696 | | |
| 5697 | | |
| 5698 | | |
| 5699 | | |
| 5707 | | |
| 5708 | | <section title="Accept" anchor="header.accept"> |
| 5709 | | <iref primary="true" item="Accept header" x:for-anchor=""/> |
| 5710 | | <iref primary="true" item="Headers" subitem="Accept" x:for-anchor=""/> |
| 5711 | | <t> |
| 5712 | | The Accept request-header field can be used to specify certain media |
| 5713 | | types which are acceptable for the response. Accept headers can be |
| 5714 | | used to indicate that the request is specifically limited to a small |
| 5715 | | set of desired types, as in the case of a request for an in-line |
| 5716 | | image. |
| 5717 | | </t> |
| 5718 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Accept"/><iref primary="true" item="Grammar" subitem="media-range"/><iref primary="true" item="Grammar" subitem="accept-params"/><iref primary="true" item="Grammar" subitem="accept-extension"/> |
| 5719 | | Accept = "Accept" ":" |
| 5720 | | #( media-range [ accept-params ] ) |
| 5721 | | |
| 5722 | | media-range = ( "*/*" |
| 5723 | | | ( type "/" "*" ) |
| 5724 | | | ( type "/" subtype ) |
| 5725 | | ) *( ";" parameter ) |
| 5726 | | accept-params = ";" "q" "=" qvalue *( accept-extension ) |
| 5727 | | accept-extension = ";" token [ "=" ( token | quoted-string ) ] |
| 5728 | | </artwork></figure> |
| 5729 | | <t> |
| 5730 | | The asterisk "*" character is used to group media types into ranges, |
| 5731 | | with "*/*" indicating all media types and "type/*" indicating all |
| 5732 | | subtypes of that type. The media-range &MAY; include media type |
| 5733 | | parameters that are applicable to that range. |
| 5734 | | </t> |
| 5735 | | <t> |
| 5736 | | Each media-range &MAY; be followed by one or more accept-params, |
| 5737 | | beginning with the "q" parameter for indicating a relative quality |
| 5738 | | factor. The first "q" parameter (if any) separates the media-range |
| 5739 | | parameter(s) from the accept-params. Quality factors allow the user |
| 5740 | | or user agent to indicate the relative degree of preference for that |
| 5741 | | media-range, using the qvalue scale from 0 to 1 (<xref target="quality.values"/>). The |
| 5742 | | default value is q=1. |
| 5743 | | <list><t> |
| 5744 | | <x:h>Note:</x:h> Use of the "q" parameter name to separate media type |
| 5745 | | parameters from Accept extension parameters is due to historical |
| 5746 | | practice. Although this prevents any media type parameter named |
| 5747 | | "q" from being used with a media range, such an event is believed |
| 5748 | | to be unlikely given the lack of any "q" parameters in the IANA |
| 5749 | | media type registry and the rare usage of any media type |
| 5750 | | parameters in Accept. Future media types are discouraged from |
| 5751 | | registering any parameter named "q". |
| 5752 | | </t></list> |
| 5753 | | </t> |
| 5754 | | <t> |
| 5755 | | The example |
| 5756 | | </t> |
| 5757 | | <figure><artwork type="example"> |
| 5758 | | Accept: audio/*; q=0.2, audio/basic |
| 5759 | | </artwork></figure> |
| 5760 | | <t> |
| 5761 | | &SHOULD; be interpreted as "I prefer audio/basic, but send me any audio |
| 5762 | | type if it is the best available after an 80% mark-down in quality." |
| 5763 | | </t> |
| 5764 | | <t> |
| 5765 | | If no Accept header field is present, then it is assumed that the |
| 5766 | | client accepts all media types. If an Accept header field is present, |
| 5767 | | and if the server cannot send a response which is acceptable |
| 5768 | | according to the combined Accept field value, then the server &SHOULD; |
| 5769 | | send a 406 (not acceptable) response. |
| 5770 | | </t> |
| 5771 | | <t> |
| 5772 | | A more elaborate example is |
| 5773 | | </t> |
| 5774 | | <figure><artwork type="example"> |
| 5775 | | Accept: text/plain; q=0.5, text/html, |
| 5776 | | text/x-dvi; q=0.8, text/x-c |
| 5777 | | </artwork></figure> |
| 5778 | | <t> |
| 5779 | | Verbally, this would be interpreted as "text/html and text/x-c are |
| 5780 | | the preferred media types, but if they do not exist, then send the |
| 5781 | | text/x-dvi entity, and if that does not exist, send the text/plain |
| 5782 | | entity." |
| 5783 | | </t> |
| 5784 | | <t> |
| 5785 | | Media ranges can be overridden by more specific media ranges or |
| 5786 | | specific media types. If more than one media range applies to a given |
| 5787 | | type, the most specific reference has precedence. For example, |
| 5788 | | </t> |
| 5789 | | <figure><artwork type="example"> |
| 5790 | | Accept: text/*, text/html, text/html;level=1, */* |
| 5791 | | </artwork></figure> |
| 5792 | | <t> |
| 5793 | | have the following precedence: |
| 5794 | | </t> |
| 5795 | | <figure><artwork type="example"> |
| 5796 | | 1) text/html;level=1 |
| 5797 | | 2) text/html |
| 5798 | | 3) text/* |
| 5799 | | 4) */* |
| 5800 | | </artwork></figure> |
| 5801 | | <t> |
| 5802 | | The media type quality factor associated with a given type is |
| 5803 | | determined by finding the media range with the highest precedence |
| 5804 | | which matches that type. For example, |
| 5805 | | </t> |
| 5806 | | <figure><artwork type="example"> |
| 5807 | | Accept: text/*;q=0.3, text/html;q=0.7, text/html;level=1, |
| 5808 | | text/html;level=2;q=0.4, */*;q=0.5 |
| 5809 | | </artwork></figure> |
| 5810 | | <t> |
| 5811 | | would cause the following values to be associated: |
| 5812 | | </t> |
| 5813 | | <figure><artwork type="example"> |
| 5814 | | text/html;level=1 = 1 |
| 5815 | | text/html = 0.7 |
| 5816 | | text/plain = 0.3 |
| 5817 | | image/jpeg = 0.5 |
| 5818 | | text/html;level=2 = 0.4 |
| 5819 | | text/html;level=3 = 0.7 |
| 5820 | | </artwork></figure> |
| 5821 | | <t> |
| 5822 | | <x:h>Note:</x:h> A user agent might be provided with a default set of quality |
| 5823 | | values for certain media ranges. However, unless the user agent is |
| 5824 | | a closed system which cannot interact with other rendering agents, |
| 5825 | | this default set ought to be configurable by the user. |
| 5826 | | </t> |
| 5827 | | </section> |
| 5828 | | |
| 5829 | | <section title="Accept-Charset" anchor="header.accept-charset"> |
| 5830 | | <iref primary="true" item="Accept-Charset header" x:for-anchor=""/> |
| 5831 | | <iref primary="true" item="Headers" subitem="Accept-Charset" x:for-anchor=""/> |
| 5832 | | <t> |
| 5833 | | The Accept-Charset request-header field can be used to indicate what |
| 5834 | | character sets are acceptable for the response. This field allows |
| 5835 | | clients capable of understanding more comprehensive or special-purpose |
| 5836 | | character sets to signal that capability to a server which is |
| 5837 | | capable of representing documents in those character sets. |
| 5838 | | </t> |
| 5839 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Accept-Charset"/> |
| 5840 | | Accept-Charset = "Accept-Charset" ":" |
| 5841 | | 1#( ( charset | "*" )[ ";" "q" "=" qvalue ] ) |
| 5842 | | </artwork></figure> |
| 5843 | | <t> |
| 5844 | | Character set values are described in <xref target="character.sets"/>. Each charset &MAY; |
| 5845 | | be given an associated quality value which represents the user's |
| 5846 | | preference for that charset. The default value is q=1. An example is |
| 5847 | | </t> |
| 5848 | | <figure><artwork type="example"> |
| 5849 | | Accept-Charset: iso-8859-5, unicode-1-1;q=0.8 |
| 5850 | | </artwork></figure> |
| 5851 | | <t> |
| 5852 | | The special value "*", if present in the Accept-Charset field, |
| 5853 | | matches every character set (including ISO-8859-1) which is not |
| 5854 | | mentioned elsewhere in the Accept-Charset field. If no "*" is present |
| 5855 | | in an Accept-Charset field, then all character sets not explicitly |
| 5856 | | mentioned get a quality value of 0, except for ISO-8859-1, which gets |
| 5857 | | a quality value of 1 if not explicitly mentioned. |
| 5858 | | </t> |
| 5859 | | <t> |
| 5860 | | If no Accept-Charset header is present, the default is that any |
| 5861 | | character set is acceptable. If an Accept-Charset header is present, |
| 5862 | | and if the server cannot send a response which is acceptable |
| 5863 | | according to the Accept-Charset header, then the server &SHOULD; send |
| 5864 | | an error response with the 406 (not acceptable) status code, though |
| 5865 | | the sending of an unacceptable response is also allowed. |
| 5866 | | </t> |
| 5867 | | </section> |
| 5868 | | |
| 5869 | | <section title="Accept-Encoding" anchor="header.accept-encoding"> |
| 5870 | | <iref primary="true" item="Accept-Encoding header" x:for-anchor=""/> |
| 5871 | | <iref primary="true" item="Headers" subitem="Accept-Encoding" x:for-anchor=""/> |
| 5872 | | <t> |
| 5873 | | The Accept-Encoding request-header field is similar to Accept, but |
| 5874 | | restricts the content-codings (<xref target="content.codings"/>) that are acceptable in |
| 5875 | | the response. |
| 5876 | | </t> |
| 5877 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Accept-Encoding"/><iref primary="true" item="Grammar" subitem="codings"/> |
| 5878 | | Accept-Encoding = "Accept-Encoding" ":" |
| 5879 | | 1#( codings [ ";" "q" "=" qvalue ] ) |
| 5880 | | codings = ( content-coding | "*" ) |
| 5881 | | </artwork></figure> |
| 5882 | | <t> |
| 5883 | | Examples of its use are: |
| 5884 | | </t> |
| 5885 | | <figure><artwork type="example"> |
| 5886 | | Accept-Encoding: compress, gzip |
| 5887 | | Accept-Encoding: |
| 5888 | | Accept-Encoding: * |
| 5889 | | Accept-Encoding: compress;q=0.5, gzip;q=1.0 |
| 5890 | | Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0 |
| 5891 | | </artwork></figure> |
| 5892 | | <t> |
| 5893 | | A server tests whether a content-coding is acceptable, according to |
| 5894 | | an Accept-Encoding field, using these rules: |
| 5895 | | <list style="numbers"> |
| 5896 | | <t>If the content-coding is one of the content-codings listed in |
| 5897 | | the Accept-Encoding field, then it is acceptable, unless it is |
| 5898 | | accompanied by a qvalue of 0. (As defined in <xref target="quality.values"/>, a |
| 5899 | | qvalue of 0 means "not acceptable.")</t> |
| 5900 | | |
| 5901 | | <t>The special "*" symbol in an Accept-Encoding field matches any |
| 5902 | | available content-coding not explicitly listed in the header |
| 5903 | | field.</t> |
| 5904 | | |
| 5905 | | <t>If multiple content-codings are acceptable, then the acceptable |
| 5906 | | content-coding with the highest non-zero qvalue is preferred.</t> |
| 5907 | | |
| 5908 | | <t>The "identity" content-coding is always acceptable, unless |
| 5909 | | specifically refused because the Accept-Encoding field includes |
| 5910 | | "identity;q=0", or because the field includes "*;q=0" and does |
| 5911 | | not explicitly include the "identity" content-coding. If the |
| 5912 | | Accept-Encoding field-value is empty, then only the "identity" |
| 5913 | | encoding is acceptable.</t> |
| 5914 | | </list> |
| 5915 | | </t> |
| 5916 | | <t> |
| 5917 | | If an Accept-Encoding field is present in a request, and if the |
| 5918 | | server cannot send a response which is acceptable according to the |
| 5919 | | Accept-Encoding header, then the server &SHOULD; send an error response |
| 5920 | | with the 406 (Not Acceptable) status code. |
| 5921 | | </t> |
| 5922 | | <t> |
| 5923 | | If no Accept-Encoding field is present in a request, the server &MAY; |
| 5924 | | assume that the client will accept any content coding. In this case, |
| 5925 | | if "identity" is one of the available content-codings, then the |
| 5926 | | server &SHOULD; use the "identity" content-coding, unless it has |
| 5927 | | additional information that a different content-coding is meaningful |
| 5928 | | to the client. |
| 5929 | | <list><t> |
| 5930 | | <x:h>Note:</x:h> If the request does not include an Accept-Encoding field, |
| 5931 | | and if the "identity" content-coding is unavailable, then |
| 5932 | | content-codings commonly understood by HTTP/1.0 clients (i.e., |
| 5933 | | "gzip" and "compress") are preferred; some older clients |
| 5934 | | improperly display messages sent with other content-codings. The |
| 5935 | | server might also make this decision based on information about |
| 5936 | | the particular user-agent or client. |
| 5937 | | </t><t> |
| 5938 | | <x:h>Note:</x:h> Most HTTP/1.0 applications do not recognize or obey qvalues |
| 5939 | | associated with content-codings. This means that qvalues will not |
| 5940 | | work and are not permitted with x-gzip or x-compress. |
| 5941 | | </t></list> |
| 5942 | | </t> |
| 5943 | | </section> |
| 5944 | | |
| 5945 | | <section title="Accept-Language" anchor="header.accept-language"> |
| 5946 | | <iref primary="true" item="Accept-Language header" x:for-anchor=""/> |
| 5947 | | <iref primary="true" item="Headers" subitem="Accept-Language" x:for-anchor=""/> |
| 5948 | | <t> |
| 5949 | | The Accept-Language request-header field is similar to Accept, but |
| 5950 | | restricts the set of natural languages that are preferred as a |
| 5951 | | response to the request. Language tags are defined in <xref target="language.tags"/>. |
| 5952 | | </t> |
| 5953 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Accept-Language"/><iref primary="true" item="Grammar" subitem="language-range"/> |
| 5954 | | Accept-Language = "Accept-Language" ":" |
| 5955 | | 1#( language-range [ ";" "q" "=" qvalue ] ) |
| 5956 | | language-range = ( ( 1*8ALPHA *( "-" 1*8ALPHA ) ) | "*" ) |
| 5957 | | </artwork></figure> |
| 5958 | | <t> |
| 5959 | | Each language-range &MAY; be given an associated quality value which |
| 5960 | | represents an estimate of the user's preference for the languages |
| 5961 | | specified by that range. The quality value defaults to "q=1". For |
| 5962 | | example, |
| 5963 | | </t> |
| 5964 | | <figure><artwork type="example"> |
| 5965 | | Accept-Language: da, en-gb;q=0.8, en;q=0.7 |
| 5966 | | </artwork></figure> |
| 5967 | | <t> |
| 5968 | | would mean: "I prefer Danish, but will accept British English and |
| 5969 | | other types of English." A language-range matches a language-tag if |
| 5970 | | it exactly equals the tag, or if it exactly equals a prefix of the |
| 5971 | | tag such that the first tag character following the prefix is "-". |
| 5972 | | The special range "*", if present in the Accept-Language field, |
| 5973 | | matches every tag not matched by any other range present in the |
| 5974 | | Accept-Language field. |
| 5975 | | <list><t> |
| 5976 | | <x:h>Note:</x:h> This use of a prefix matching rule does not imply that |
| 5977 | | language tags are assigned to languages in such a way that it is |
| 5978 | | always true that if a user understands a language with a certain |
| 5979 | | tag, then this user will also understand all languages with tags |
| 5980 | | for which this tag is a prefix. The prefix rule simply allows the |
| 5981 | | use of prefix tags if this is the case. |
| 5982 | | </t></list> |
| 5983 | | </t> |
| 5984 | | <t> |
| 5985 | | The language quality factor assigned to a language-tag by the |
| 5986 | | Accept-Language field is the quality value of the longest language-range |
| 5987 | | in the field that matches the language-tag. If no language-range |
| 5988 | | in the field matches the tag, the language quality factor |
| 5989 | | assigned is 0. If no Accept-Language header is present in the |
| 5990 | | request, the server |
| 5991 | | &SHOULD; assume that all languages are equally acceptable. If an |
| 5992 | | Accept-Language header is present, then all languages which are |
| 5993 | | assigned a quality factor greater than 0 are acceptable. |
| 5994 | | </t> |
| 5995 | | <t> |
| 5996 | | It might be contrary to the privacy expectations of the user to send |
| 5997 | | an Accept-Language header with the complete linguistic preferences of |
| 5998 | | the user in every request. For a discussion of this issue, see |
| 5999 | | <xref target="privacy.issues.connected.to.accept.headers"/>. |
| 6000 | | </t> |
| 6001 | | <t> |
| 6002 | | As intelligibility is highly dependent on the individual user, it is |
| 6003 | | recommended that client applications make the choice of linguistic |
| 6004 | | preference available to the user. If the choice is not made |
| 6005 | | available, then the Accept-Language header field &MUST-NOT; be given in |
| 6006 | | the request. |
| 6007 | | <list><t> |
| 6008 | | <x:h>Note:</x:h> When making the choice of linguistic preference available to |
| 6009 | | the user, we remind implementors of the fact that users are not |
| 6010 | | familiar with the details of language matching as described above, |
| 6011 | | and should provide appropriate guidance. As an example, users |
| 6012 | | might assume that on selecting "en-gb", they will be served any |
| 6013 | | kind of English document if British English is not available. A |
| 6014 | | user agent might suggest in such a case to add "en" to get the |
| 6015 | | best matching behavior. |
| 6016 | | </t></list> |
| 6017 | | </t> |
| 6018 | | </section> |
| 6019 | | |
| 6020 | | <section title="Accept-Ranges" anchor="header.accept-ranges"> |
| 6021 | | <iref primary="true" item="Accept-Ranges header" x:for-anchor=""/> |
| 6022 | | <iref primary="true" item="Headers" subitem="Accept-Ranges" x:for-anchor=""/> |
| 6023 | | <t> |
| 6024 | | The Accept-Ranges response-header field allows the server to |
| 6025 | | indicate its acceptance of range requests for a resource: |
| 6026 | | </t> |
| 6027 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Accept-Ranges"/><iref primary="true" item="Grammar" subitem="acceptable-ranges"/> |
| 6028 | | Accept-Ranges = "Accept-Ranges" ":" acceptable-ranges |
| 6029 | | acceptable-ranges = 1#range-unit | "none" |
| 6030 | | </artwork></figure> |
| 6031 | | <t> |
| 6032 | | Origin servers that accept byte-range requests &MAY; send |
| 6033 | | </t> |
| 6034 | | <figure><artwork type="example"> |
| 6035 | | Accept-Ranges: bytes |
| 6036 | | </artwork></figure> |
| 6037 | | <t> |
| 6038 | | but are not required to do so. Clients &MAY; generate byte-range |
| 6039 | | requests without having received this header for the resource |
| 6040 | | involved. Range units are defined in <xref target="range.units"/>. |
| 6041 | | </t> |
| 6042 | | <t> |
| 6043 | | Servers that do not accept any kind of range request for a |
| 6044 | | resource &MAY; send |
| 6045 | | </t> |
| 6046 | | <figure><artwork type="example"> |
| 6047 | | Accept-Ranges: none |
| 6048 | | </artwork></figure> |
| 6049 | | <t> |
| 6050 | | to advise the client not to attempt a range request. |
| 6051 | | </t> |
| 6052 | | </section> |
| 6053 | | |
| 6054 | | <section title="Age" anchor="header.age"> |
| 6055 | | <iref primary="true" item="Age header" x:for-anchor=""/> |
| 6056 | | <iref primary="true" item="Headers" subitem="Age" x:for-anchor=""/> |
| 6057 | | <t> |
| 6058 | | The Age response-header field conveys the sender's estimate of the |
| 6059 | | amount of time since the response (or its revalidation) was |
| 6060 | | generated at the origin server. A cached response is "fresh" if |
| 6061 | | its age does not exceed its freshness lifetime. Age values are |
| 6062 | | calculated as specified in <xref target="age.calculations"/>. |
| 6063 | | </t> |
| 6064 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Age"/><iref primary="true" item="Grammar" subitem="age-value"/> |
| 6065 | | Age = "Age" ":" age-value |
| 6066 | | age-value = delta-seconds |
| 6067 | | </artwork></figure> |
| 6068 | | <t> |
| 6069 | | Age values are non-negative decimal integers, representing time in |
| 6070 | | seconds. |
| 6071 | | </t> |
| 6072 | | <t> |
| 6073 | | If a cache receives a value larger than the largest positive |
| 6074 | | integer it can represent, or if any of its age calculations |
| 6075 | | overflows, it &MUST; transmit an Age header with a value of |
| 6076 | | 2147483648 (2^31). An HTTP/1.1 server that includes a cache &MUST; |
| 6077 | | include an Age header field in every response generated from its |
| 6078 | | own cache. Caches &SHOULD; use an arithmetic type of at least 31 |
| 6079 | | bits of range. |
| 6080 | | </t> |
| 6081 | | </section> |
| 6082 | | |
| 6083 | | <section title="Allow" anchor="header.allow"> |
| 6084 | | <iref primary="true" item="Allow header" x:for-anchor=""/> |
| 6085 | | <iref primary="true" item="Headers" subitem="Allow" x:for-anchor=""/> |
| 6086 | | <t> |
| 6087 | | The Allow entity-header field lists the set of methods supported |
| 6088 | | by the resource identified by the Request-URI. The purpose of this |
| 6089 | | field is strictly to inform the recipient of valid methods |
| 6090 | | associated with the resource. An Allow header field &MUST; be |
| 6091 | | present in a 405 (Method Not Allowed) response. |
| 6092 | | </t> |
| 6093 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Allow"/> |
| 6094 | | Allow = "Allow" ":" #Method |
| 6095 | | </artwork></figure> |
| 6096 | | <t> |
| 6097 | | Example of use: |
| 6098 | | </t> |
| 6099 | | <figure><artwork type="example"> |
| 6100 | | Allow: GET, HEAD, PUT |
| 6101 | | </artwork></figure> |
| 6102 | | <t> |
| 6103 | | This field cannot prevent a client from trying other methods. |
| 6104 | | However, the indications given by the Allow header field value |
| 6105 | | &SHOULD; be followed. The actual set of allowed methods is defined |
| 6106 | | by the origin server at the time of each request. |
| 6107 | | </t> |
| 6108 | | <t> |
| 6109 | | The Allow header field &MAY; be provided with a PUT request to |
| 6110 | | recommend the methods to be supported by the new or modified |
| 6111 | | resource. The server is not required to support these methods and |
| 6112 | | &SHOULD; include an Allow header in the response giving the actual |
| 6113 | | supported methods. |
| 6114 | | </t> |
| 6115 | | <t> |
| 6116 | | A proxy &MUST-NOT; modify the Allow header field even if it does not |
| 6117 | | understand all the methods specified, since the user agent might |
| 6118 | | have other means of communicating with the origin server. |
| 6119 | | </t> |
| 6120 | | </section> |
| 6121 | | |
| 6122 | | <section title="Authorization" anchor="header.authorization"> |
| 6123 | | <iref primary="true" item="Authorization header" x:for-anchor=""/> |
| 6124 | | <iref primary="true" item="Headers" subitem="Authorization" x:for-anchor=""/> |
| 6125 | | <t> |
| 6126 | | A user agent that wishes to authenticate itself with a server-- |
| 6127 | | usually, but not necessarily, after receiving a 401 response--does |
| 6128 | | so by including an Authorization request-header field with the |
| 6129 | | request. The Authorization field value consists of credentials |
| 6130 | | containing the authentication information of the user agent for |
| 6131 | | the realm of the resource being requested. |
| 6132 | | </t> |
| 6133 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Authorization"/> |
| 6134 | | Authorization = "Authorization" ":" credentials |
| 6135 | | </artwork></figure> |
| 6136 | | <t> |
| 6137 | | HTTP access authentication is described in "HTTP Authentication: |
| 6138 | | Basic and Digest Access Authentication" <xref target="RFC2617"/>. If a request is |
| 6139 | | authenticated and a realm specified, the same credentials &SHOULD; |
| 6140 | | be valid for all other requests within this realm (assuming that |
| 6141 | | the authentication scheme itself does not require otherwise, such |
| 6142 | | as credentials that vary according to a challenge value or using |
| 6143 | | synchronized clocks). |
| 6144 | | </t> |
| 6145 | | <t> |
| 6146 | | When a shared cache (see <xref target="shared.and.non-shared.caches"/>) receives a request |
| 6147 | | containing an Authorization field, it &MUST-NOT; return the |
| 6148 | | corresponding response as a reply to any other request, unless one |
| 6149 | | of the following specific exceptions holds: |
| 6150 | | </t> |
| 6151 | | <t> |
| 6152 | | <list style="numbers"> |
| 6153 | | <t>If the response includes the "s-maxage" cache-control |
| 6154 | | directive, the cache &MAY; use that response in replying to a |
| 6155 | | subsequent request. But (if the specified maximum age has |
| 6156 | | passed) a proxy cache &MUST; first revalidate it with the origin |
| 6157 | | server, using the request-headers from the new request to allow |
| 6158 | | the origin server to authenticate the new request. (This is the |
| 6159 | | defined behavior for s-maxage.) If the response includes "s-maxage=0", |
| 6160 | | the proxy &MUST; always revalidate it before re-using |
| 6161 | | it.</t> |
| 6162 | | |
| 6163 | | <t>If the response includes the "must-revalidate" cache-control |
| 6164 | | directive, the cache &MAY; use that response in replying to a |
| 6165 | | subsequent request. But if the response is stale, all caches |
| 6166 | | &MUST; first revalidate it with the origin server, using the |
| 6167 | | request-headers from the new request to allow the origin server |
| 6168 | | to authenticate the new request.</t> |
| 6169 | | |
| 6170 | | <t>If the response includes the "public" cache-control directive, |
| 6171 | | it &MAY; be returned in reply to any subsequent request.</t> |
| 6172 | | </list> |
| 6173 | | </t> |
| 6174 | | </section> |
| 6175 | | |
| 6176 | | <section title="Cache-Control" anchor="header.cache-control"> |
| 6177 | | <iref primary="true" item="Cache-Control header" x:for-anchor=""/> |
| 6178 | | <iref primary="true" item="Headers" subitem="Cache-Control" x:for-anchor=""/> |
| 6179 | | <t> |
| 6180 | | The Cache-Control general-header field is used to specify directives |
| 6181 | | that &MUST; be obeyed by all caching mechanisms along the |
| 6182 | | request/response chain. The directives specify behavior intended to |
| 6183 | | prevent caches from adversely interfering with the request or |
| 6184 | | response. These directives typically override the default caching |
| 6185 | | algorithms. Cache directives are unidirectional in that the presence |
| 6186 | | of a directive in a request does not imply that the same directive is |
| 6187 | | to be given in the response. |
| 6188 | | <list><t> |
| 6189 | | Note that HTTP/1.0 caches might not implement Cache-Control and |
| 6190 | | might only implement Pragma: no-cache (see <xref target="header.pragma"/>). |
| 6191 | | </t></list> |
| 6192 | | </t> |
| 6193 | | <t> |
| 6194 | | Cache directives &MUST; be passed through by a proxy or gateway |
| 6195 | | application, regardless of their significance to that application, |
| 6196 | | since the directives might be applicable to all recipients along the |
| 6197 | | request/response chain. It is not possible to specify a cache-directive |
| 6198 | | for a specific cache. |
| 6199 | | </t> |
| 6200 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Cache-Control"/><iref primary="true" item="Grammar" subitem="cache-directive"/><iref primary="true" item="Grammar" subitem="cache-request-directive"/><iref primary="true" item="Grammar" subitem="cache-response-directive"/><iref primary="true" item="Grammar" subitem="cache-extension"/> |
| 6201 | | Cache-Control = "Cache-Control" ":" 1#cache-directive |
| 6202 | | |
| 6203 | | cache-directive = cache-request-directive |
| 6204 | | | cache-response-directive |
| 6205 | | |
| 6206 | | cache-request-directive = |
| 6207 | | "no-cache" ; <xref target="what.is.cacheable"/> |
| 6208 | | | "no-store" ; <xref target="what.may.be.stored.by.caches"/> |
| 6209 | | | "max-age" "=" delta-seconds ; <xref target="modifications.of.the.basic.expiration.mechanism"/>, <xref format="counter" target="cache.revalidation.and.reload.controls"/> |
| 6210 | | | "max-stale" [ "=" delta-seconds ] ; <xref target="modifications.of.the.basic.expiration.mechanism"/> |
| 6211 | | | "min-fresh" "=" delta-seconds ; <xref target="modifications.of.the.basic.expiration.mechanism"/> |
| 6212 | | | "no-transform" ; <xref target="no-transform.directive"/> |
| 6213 | | | "only-if-cached" ; <xref target="cache.revalidation.and.reload.controls"/> |
| 6214 | | | cache-extension ; <xref target="cache.control.extensions"/> |
| 6215 | | |
| 6216 | | cache-response-directive = |
| 6217 | | "public" ; <xref target="what.is.cacheable"/> |
| 6218 | | | "private" [ "=" <"> 1#field-name <"> ] ; <xref target="what.is.cacheable"/> |
| 6219 | | | "no-cache" [ "=" <"> 1#field-name <"> ]; <xref target="what.is.cacheable"/> |
| 6220 | | | "no-store" ; <xref target="what.may.be.stored.by.caches"/> |
| 6221 | | | "no-transform" ; <xref target="no-transform.directive"/> |
| 6222 | | | "must-revalidate" ; <xref target="cache.revalidation.and.reload.controls"/> |
| 6223 | | | "proxy-revalidate" ; <xref target="cache.revalidation.and.reload.controls"/> |
| 6224 | | | "max-age" "=" delta-seconds ; <xref target="modifications.of.the.basic.expiration.mechanism"/> |
| 6225 | | | "s-maxage" "=" delta-seconds ; <xref target="modifications.of.the.basic.expiration.mechanism"/> |
| 6226 | | | cache-extension ; <xref target="cache.control.extensions"/> |
| 6227 | | |
| 6228 | | cache-extension = token [ "=" ( token | quoted-string ) ] |
| 6229 | | </artwork></figure> |
| 6230 | | <t> |
| 6231 | | When a directive appears without any 1#field-name parameter, the |
| 6232 | | directive applies to the entire request or response. When such a |
| 6233 | | directive appears with a 1#field-name parameter, it applies only to |
| 6234 | | the named field or fields, and not to the rest of the request or |
| 6235 | | response. This mechanism supports extensibility; implementations of |
| 6236 | | future versions of the HTTP protocol might apply these directives to |
| 6237 | | header fields not defined in HTTP/1.1. |
| 6238 | | </t> |
| 6239 | | <t> |
| 6240 | | The cache-control directives can be broken down into these general |
| 6241 | | categories: |
| 6242 | | <list style="symbols"> |
| 6243 | | <t>Restrictions on what are cacheable; these may only be imposed by |
| 6244 | | the origin server.</t> |
| 6245 | | |
| 6246 | | <t>Restrictions on what may be stored by a cache; these may be |
| 6247 | | imposed by either the origin server or the user agent.</t> |
| 6248 | | |
| 6249 | | <t>Modifications of the basic expiration mechanism; these may be |
| 6250 | | imposed by either the origin server or the user agent.</t> |
| 6251 | | |
| 6252 | | <t>Controls over cache revalidation and reload; these may only be |
| 6253 | | imposed by a user agent.</t> |
| 6254 | | |
| 6255 | | <t>Control over transformation of entities.</t> |
| 6256 | | |
| 6257 | | <t>Extensions to the caching system.</t> |
| 6258 | | </list> |
| 6259 | | </t> |
| 6260 | | |
| 6261 | | <section title="What is Cacheable" anchor="what.is.cacheable"> |
| 6262 | | <t> |
| 6263 | | By default, a response is cacheable if the requirements of the |
| 6264 | | request method, request header fields, and the response status |
| 6265 | | indicate that it is cacheable. <xref target="response.cacheability"/> summarizes these defaults |
| 6266 | | for cacheability. The following Cache-Control response directives |
| 6267 | | allow an origin server to override the default cacheability of a |
| 6268 | | response: |
| 6269 | | </t> |
| 6270 | | <t> |
| 6271 | | <iref item="Cache Directives" subitem="public" primary="true"/> |
| 6272 | | <iref item="public" subitem="Cache Directive" primary="true"/> |
| 6273 | | public |
| 6274 | | <list><t> |
| 6275 | | Indicates that the response &MAY; be cached by any cache, even if it |
| 6276 | | would normally be non-cacheable or cacheable only within a non-shared |
| 6277 | | cache. (See also Authorization, <xref target="header.authorization"/>, for |
| 6278 | | additional details.) |
| 6279 | | </t></list> |
| 6280 | | </t> |
| 6281 | | <t> |
| 6282 | | <iref item="Cache Directives" subitem="private" primary="true"/> |
| 6283 | | <iref item="private" subitem="Cache Directive" primary="true"/> |
| 6284 | | private |
| 6285 | | <list><t> |
| 6286 | | Indicates that all or part of the response message is intended for |
| 6287 | | a single user and &MUST-NOT; be cached by a shared cache. This |
| 6288 | | allows an origin server to state that the specified parts of the |
| 6289 | | response are intended for only one user and are not a valid |
| 6290 | | response for requests by other users. A private (non-shared) cache |
| 6291 | | &MAY; cache the response. |
| 6292 | | </t><t> |
| 6293 | | <x:h>Note:</x:h> This usage of the word private only controls where the |
| 6294 | | response may be cached, and cannot ensure the privacy of the |
| 6295 | | message content. |
| 6296 | | </t></list> |
| 6297 | | </t> |
| 6298 | | <t> |
| 6299 | | <iref item="Cache Directives" subitem="no-cache" primary="true"/> |
| 6300 | | <iref item="no-cache" subitem="Cache Directive" primary="true"/> |
| 6301 | | no-cache |
| 6302 | | <list><t> |
| 6303 | | If the no-cache directive does not specify a field-name, then a |
| 6304 | | cache &MUST-NOT; use the response to satisfy a subsequent request |
| 6305 | | without successful revalidation with the origin server. This |
| 6306 | | allows an origin server to prevent caching even by caches that |
| 6307 | | have been configured to return stale responses to client requests. |
| 6308 | | </t><t> |
| 6309 | | If the no-cache directive does specify one or more field-names, |
| 6310 | | then a cache &MAY; use the response to satisfy a subsequent request, |
| 6311 | | subject to any other restrictions on caching. However, the |
| 6312 | | specified field-name(s) &MUST-NOT; be sent in the response to a |
| 6313 | | subsequent request without successful revalidation with the origin |
| 6314 | | server. This allows an origin server to prevent the re-use of |
| 6315 | | certain header fields in a response, while still allowing caching |
| 6316 | | of the rest of the response. |
| 6317 | | <list><t> |
| 6318 | | <x:h>Note:</x:h> Most HTTP/1.0 caches will not recognize or obey this |
| 6319 | | directive. |
| 6320 | | </t></list> |
| 6321 | | </t></list> |
| 6322 | | </t> |
| 6323 | | </section> |
| 6324 | | |
| 6325 | | <section title="What May be Stored by Caches" anchor="what.may.be.stored.by.caches"> |
| 6326 | | <t> |
| 6327 | | <iref item="Cache Directives" subitem="no-store" primary="true"/> |
| 6328 | | <iref item="no-store" subitem="Cache Directive" primary="true"/> |
| 6329 | | no-store |
| 6330 | | <list><t> |
| 6331 | | The purpose of the no-store directive is to prevent the |
| 6332 | | inadvertent release or retention of sensitive information (for |
| 6333 | | example, on backup tapes). The no-store directive applies to the |
| 6334 | | entire message, and &MAY; be sent either in a response or in a |
| 6335 | | request. If sent in a request, a cache &MUST-NOT; store any part of |
| 6336 | | either this request or any response to it. If sent in a response, |
| 6337 | | a cache &MUST-NOT; store any part of either this response or the |
| 6338 | | request that elicited it. This directive applies to both non-shared |
| 6339 | | and shared caches. "&MUST-NOT; store" in this context means |
| 6340 | | that the cache &MUST-NOT; intentionally store the information in |
| 6341 | | non-volatile storage, and &MUST; make a best-effort attempt to |
| 6342 | | remove the information from volatile storage as promptly as |
| 6343 | | possible after forwarding it. |
| 6344 | | </t><t> |
| 6345 | | Even when this directive is associated with a response, users |
| 6346 | | might explicitly store such a response outside of the caching |
| 6347 | | system (e.g., with a "Save As" dialog). History buffers &MAY; store |
| 6348 | | such responses as part of their normal operation. |
| 6349 | | </t><t> |
| 6350 | | The purpose of this directive is to meet the stated requirements |
| 6351 | | of certain users and service authors who are concerned about |
| 6352 | | accidental releases of information via unanticipated accesses to |
| 6353 | | cache data structures. While the use of this directive might |
| 6354 | | improve privacy in some cases, we caution that it is NOT in any |
| 6355 | | way a reliable or sufficient mechanism for ensuring privacy. In |
| 6356 | | particular, malicious or compromised caches might not recognize or |
| 6357 | | obey this directive, and communications networks might be |
| 6358 | | vulnerable to eavesdropping. |
| 6359 | | </t></list> |
| 6360 | | </t> |
| 6361 | | </section> |
| 6362 | | |
| 6363 | | <section title="Modifications of the Basic Expiration Mechanism" anchor="modifications.of.the.basic.expiration.mechanism"> |
| 6364 | | <t> |
| 6365 | | The expiration time of an entity &MAY; be specified by the origin |
| 6366 | | server using the Expires header (see <xref target="header.expires"/>). Alternatively, |
| 6367 | | it &MAY; be specified using the max-age directive in a response. When |
| 6368 | | the max-age cache-control directive is present in a cached response, |
| 6369 | | the response is stale if its current age is greater than the age |
| 6370 | | value given (in seconds) at the time of a new request for that |
| 6371 | | resource. The max-age directive on a response implies that the |
| 6372 | | response is cacheable (i.e., "public") unless some other, more |
| 6373 | | restrictive cache directive is also present. |
| 6374 | | </t> |
| 6375 | | <t> |
| 6376 | | If a response includes both an Expires header and a max-age |
| 6377 | | directive, the max-age directive overrides the Expires header, even |
| 6378 | | if the Expires header is more restrictive. This rule allows an origin |
| 6379 | | server to provide, for a given response, a longer expiration time to |
| 6380 | | an HTTP/1.1 (or later) cache than to an HTTP/1.0 cache. This might be |
| 6381 | | useful if certain HTTP/1.0 caches improperly calculate ages or |
| 6382 | | expiration times, perhaps due to desynchronized clocks. |
| 6383 | | </t> |
| 6384 | | <t> |
| 6385 | | Many HTTP/1.0 cache implementations will treat an Expires value that |
| 6386 | | is less than or equal to the response Date value as being equivalent |
| 6387 | | to the Cache-Control response directive "no-cache". If an HTTP/1.1 |
| 6388 | | cache receives such a response, and the response does not include a |
| 6389 | | Cache-Control header field, it &SHOULD; consider the response to be |
| 6390 | | non-cacheable in order to retain compatibility with HTTP/1.0 servers. |
| 6391 | | <list><t> |
| 6392 | | <x:h>Note:</x:h> An origin server might wish to use a relatively new HTTP |
| 6393 | | cache control feature, such as the "private" directive, on a |
| 6394 | | network including older caches that do not understand that |
| 6395 | | feature. The origin server will need to combine the new feature |
| 6396 | | with an Expires field whose value is less than or equal to the |
| 6397 | | Date value. This will prevent older caches from improperly |
| 6398 | | caching the response. |
| 6399 | | </t></list> |
| 6400 | | </t> |
| 6401 | | <t> |
| 6402 | | <iref item="Cache Directives" subitem="s-maxage" primary="true"/> |
| 6403 | | <iref item="s-maxage" subitem="Cache Directive" primary="true"/> |
| 6404 | | s-maxage |
| 6405 | | <list><t> |
| 6406 | | If a response includes an s-maxage directive, then for a shared |
| 6407 | | cache (but not for a private cache), the maximum age specified by |
| 6408 | | this directive overrides the maximum age specified by either the |
| 6409 | | max-age directive or the Expires header. The s-maxage directive |
| 6410 | | also implies the semantics of the proxy-revalidate directive (see |
| 6411 | | <xref target="cache.revalidation.and.reload.controls"/>), i.e., that the shared cache must not use the |
| 6412 | | entry after it becomes stale to respond to a subsequent request |
| 6413 | | without first revalidating it with the origin server. The s-maxage |
| 6414 | | directive is always ignored by a private cache. |
| 6415 | | </t></list> |
| 6416 | | </t> |
| 6417 | | <t> |
| 6418 | | Note that most older caches, not compliant with this specification, |
| 6419 | | do not implement any cache-control directives. An origin server |
| 6420 | | wishing to use a cache-control directive that restricts, but does not |
| 6421 | | prevent, caching by an HTTP/1.1-compliant cache &MAY; exploit the |
| 6422 | | requirement that the max-age directive overrides the Expires header, |
| 6423 | | and the fact that pre-HTTP/1.1-compliant caches do not observe the |
| 6424 | | max-age directive. |
| 6425 | | </t> |
| 6426 | | <t> |
| 6427 | | Other directives allow a user agent to modify the basic expiration |
| 6428 | | mechanism. These directives &MAY; be specified on a request: |
| 6429 | | </t> |
| 6430 | | <t> |
| 6431 | | <iref item="Cache Directives" subitem="max-age" primary="true"/> |
| 6432 | | <iref item="max-age" subitem="Cache Directive" primary="true"/> |
| 6433 | | max-age |
| 6434 | | <list><t> |
| 6435 | | Indicates that the client is willing to accept a response whose |
| 6436 | | age is no greater than the specified time in seconds. Unless max-stale |
| 6437 | | directive is also included, the client is not willing to |
| 6438 | | accept a stale response. |
| 6439 | | </t></list> |
| 6440 | | </t> |
| 6441 | | <t> |
| 6442 | | <iref item="Cache Directives" subitem="min-fresh" primary="true"/> |
| 6443 | | <iref item="min-fresh" subitem="Cache Directive" primary="true"/> |
| 6444 | | min-fresh |
| 6445 | | <list><t> |
| 6446 | | Indicates that the client is willing to accept a response whose |
| 6447 | | freshness lifetime is no less than its current age plus the |
| 6448 | | specified time in seconds. That is, the client wants a response |
| 6449 | | that will still be fresh for at least the specified number of |
| 6450 | | seconds. |
| 6451 | | </t></list> |
| 6452 | | </t> |
| 6453 | | <t> |
| 6454 | | <iref item="Cache Directives" subitem="max-stale" primary="true"/> |
| 6455 | | <iref item="max-stale" subitem="Cache Directive" primary="true"/> |
| 6456 | | max-stale |
| 6457 | | <list><t> |
| 6458 | | Indicates that the client is willing to accept a response that has |
| 6459 | | exceeded its expiration time. If max-stale is assigned a value, |
| 6460 | | then the client is willing to accept a response that has exceeded |
| 6461 | | its expiration time by no more than the specified number of |
| 6462 | | seconds. If no value is assigned to max-stale, then the client is |
| 6463 | | willing to accept a stale response of any age. |
| 6464 | | </t></list> |
| 6465 | | </t> |
| 6466 | | <t> |
| 6467 | | If a cache returns a stale response, either because of a max-stale |
| 6468 | | directive on a request, or because the cache is configured to |
| 6469 | | override the expiration time of a response, the cache &MUST; attach a |
| 6470 | | Warning header to the stale response, using Warning 110 (Response is |
| 6471 | | stale). |
| 6472 | | </t> |
| 6473 | | <t> |
| 6474 | | A cache &MAY; be configured to return stale responses without |
| 6475 | | validation, but only if this does not conflict with any "MUST"-level |
| 6476 | | requirements concerning cache validation (e.g., a "must-revalidate" |
| 6477 | | cache-control directive). |
| 6478 | | </t> |
| 6479 | | <t> |
| 6480 | | If both the new request and the cached entry include "max-age" |
| 6481 | | directives, then the lesser of the two values is used for determining |
| 6482 | | the freshness of the cached entry for that request. |
| 6483 | | </t> |
| 6484 | | </section> |
| 6485 | | |
| 6486 | | <section title="Cache Revalidation and Reload Controls" anchor="cache.revalidation.and.reload.controls"> |
| 6487 | | <t> |
| 6488 | | Sometimes a user agent might want or need to insist that a cache |
| 6489 | | revalidate its cache entry with the origin server (and not just with |
| 6490 | | the next cache along the path to the origin server), or to reload its |
| 6491 | | cache entry from the origin server. End-to-end revalidation might be |
| 6492 | | necessary if either the cache or the origin server has overestimated |
| 6493 | | the expiration time of the cached response. End-to-end reload may be |
| 6494 | | necessary if the cache entry has become corrupted for some reason. |
| 6495 | | </t> |
| 6496 | | <t> |
| 6497 | | End-to-end revalidation may be requested either when the client does |
| 6498 | | not have its own local cached copy, in which case we call it |
| 6499 | | "unspecified end-to-end revalidation", or when the client does have a |
| 6500 | | local cached copy, in which case we call it "specific end-to-end |
| 6501 | | revalidation." |
| 6502 | | </t> |
| 6503 | | <t> |
| 6504 | | The client can specify these three kinds of action using Cache-Control |
| 6505 | | request directives: |
| 6506 | | </t> |
| 6507 | | <t> |
| 6508 | | End-to-end reload |
| 6509 | | <list><t> |
| 6510 | | The request includes a "no-cache" cache-control directive or, for |
| 6511 | | compatibility with HTTP/1.0 clients, "Pragma: no-cache". Field |
| 6512 | | names &MUST-NOT; be included with the no-cache directive in a |
| 6513 | | request. The server &MUST-NOT; use a cached copy when responding to |
| 6514 | | such a request. |
| 6515 | | </t></list> |
| 6516 | | </t> |
| 6517 | | <t> |
| 6518 | | Specific end-to-end revalidation |
| 6519 | | <list><t> |
| 6520 | | The request includes a "max-age=0" cache-control directive, which |
| 6521 | | forces each cache along the path to the origin server to |
| 6522 | | revalidate its own entry, if any, with the next cache or server. |
| 6523 | | The initial request includes a cache-validating conditional with |
| 6524 | | the client's current validator. |
| 6525 | | </t></list> |
| 6526 | | </t> |
| 6527 | | <t> |
| 6528 | | Unspecified end-to-end revalidation |
| 6529 | | <list><t> |
| 6530 | | The request includes "max-age=0" cache-control directive, which |
| 6531 | | forces each cache along the path to the origin server to |
| 6532 | | revalidate its own entry, if any, with the next cache or server. |
| 6533 | | The initial request does not include a cache-validating |
| 6534 | | conditional; the first cache along the path (if any) that holds a |
| 6535 | | cache entry for this resource includes a cache-validating |
| 6536 | | conditional with its current validator. |
| 6537 | | </t></list> |
| 6538 | | </t> |
| 6539 | | <t> |
| 6540 | | <iref item="Cache Directives" subitem="max-age" primary="true"/> |
| 6541 | | <iref item="max-age" subitem="Cache Directive" primary="true"/> |
| 6542 | | max-age |
| 6543 | | <list><t> |
| 6544 | | When an intermediate cache is forced, by means of a max-age=0 |
| 6545 | | directive, to revalidate its own cache entry, and the client has |
| 6546 | | supplied its own validator in the request, the supplied validator |
| 6547 | | might differ from the validator currently stored with the cache |
| 6548 | | entry. In this case, the cache &MAY; use either validator in making |
| 6549 | | its own request without affecting semantic transparency. |
| 6550 | | </t><t> |
| 6551 | | However, the choice of validator might affect performance. The |
| 6552 | | best approach is for the intermediate cache to use its own |
| 6553 | | validator when making its request. If the server replies with 304 |
| 6554 | | (Not Modified), then the cache can return its now validated copy |
| 6555 | | to the client with a 200 (OK) response. If the server replies with |
| 6556 | | a new entity and cache validator, however, the intermediate cache |
| 6557 | | can compare the returned validator with the one provided in the |
| 6558 | | client's request, using the strong comparison function. If the |
| 6559 | | client's validator is equal to the origin server's, then the |
| 6560 | | intermediate cache simply returns 304 (Not Modified). Otherwise, |
| 6561 | | it returns the new entity with a 200 (OK) response. |
| 6562 | | </t><t> |
| 6563 | | If a request includes the no-cache directive, it &SHOULD-NOT; |
| 6564 | | include min-fresh, max-stale, or max-age. |
| 6565 | | </t></list> |
| 6566 | | </t> |
| 6567 | | <t> |
| 6568 | | <iref item="Cache Directives" subitem="only-if-cached" primary="true"/> |
| 6569 | | <iref item="only-if-cached" subitem="Cache Directive" primary="true"/> |
| 6570 | | only-if-cached |
| 6571 | | <list><t> |
| 6572 | | In some cases, such as times of extremely poor network |
| 6573 | | connectivity, a client may want a cache to return only those |
| 6574 | | responses that it currently has stored, and not to reload or |
| 6575 | | revalidate with the origin server. To do this, the client may |
| 6576 | | include the only-if-cached directive in a request. If it receives |
| 6577 | | this directive, a cache &SHOULD; either respond using a cached entry |
| 6578 | | that is consistent with the other constraints of the request, or |
| 6579 | | respond with a 504 (Gateway Timeout) status. However, if a group |
| 6580 | | of caches is being operated as a unified system with good internal |
| 6581 | | connectivity, such a request &MAY; be forwarded within that group of |
| 6582 | | caches. |
| 6583 | | </t></list> |
| 6584 | | </t> |
| 6585 | | <t> |
| 6586 | | <iref item="Cache Directives" subitem="must-revalidate" primary="true"/> |
| 6587 | | <iref item="must-revalidate" subitem="Cache Directive" primary="true"/> |
| 6588 | | must-revalidate |
| 6589 | | <list><t> |
| 6590 | | Because a cache &MAY; be configured to ignore a server's specified |
| 6591 | | expiration time, and because a client request &MAY; include a max-stale |
| 6592 | | directive (which has a similar effect), the protocol also |
| 6593 | | includes a mechanism for the origin server to require revalidation |
| 6594 | | of a cache entry on any subsequent use. When the must-revalidate |
| 6595 | | directive is present in a response received by a cache, that cache |
| 6596 | | &MUST-NOT; use the entry after it becomes stale to respond to a |
| 6597 | | subsequent request without first revalidating it with the origin |
| 6598 | | server. (I.e., the cache &MUST; do an end-to-end revalidation every |
| 6599 | | time, if, based solely on the origin server's Expires or max-age |
| 6600 | | value, the cached response is stale.) |
| 6601 | | </t><t> |
| 6602 | | The must-revalidate directive is necessary to support reliable |
| 6603 | | operation for certain protocol features. In all circumstances an |
| 6604 | | HTTP/1.1 cache &MUST; obey the must-revalidate directive; in |
| 6605 | | particular, if the cache cannot reach the origin server for any |
| 6606 | | reason, it &MUST; generate a 504 (Gateway Timeout) response. |
| 6607 | | </t><t> |
| 6608 | | Servers &SHOULD; send the must-revalidate directive if and only if |
| 6609 | | failure to revalidate a request on the entity could result in |
| 6610 | | incorrect operation, such as a silently unexecuted financial |
| 6611 | | transaction. Recipients &MUST-NOT; take any automated action that |
| 6612 | | violates this directive, and &MUST-NOT; automatically provide an |
| 6613 | | unvalidated copy of the entity if revalidation fails. |
| 6614 | | </t><t> |
| 6615 | | Although this is not recommended, user agents operating under |
| 6616 | | severe connectivity constraints &MAY; violate this directive but, if |
| 6617 | | so, &MUST; explicitly warn the user that an unvalidated response has |
| 6618 | | been provided. The warning &MUST; be provided on each unvalidated |
| 6619 | | access, and &SHOULD; require explicit user confirmation. |
| 6620 | | </t></list> |
| 6621 | | </t> |
| 6622 | | <t> |
| 6623 | | <iref item="Cache Directives" subitem="proxy-revalidate" primary="true"/> |
| 6624 | | <iref item="proxy-revalidate" subitem="Cache Directive" primary="true"/> |
| 6625 | | proxy-revalidate |
| 6626 | | <list><t> |
| 6627 | | The proxy-revalidate directive has the same meaning as the must-revalidate |
| 6628 | | directive, except that it does not apply to non-shared |
| 6629 | | user agent caches. It can be used on a response to an |
| 6630 | | authenticated request to permit the user's cache to store and |
| 6631 | | later return the response without needing to revalidate it (since |
| 6632 | | it has already been authenticated once by that user), while still |
| 6633 | | requiring proxies that service many users to revalidate each time |
| 6634 | | (in order to make sure that each user has been authenticated). |
| 6635 | | Note that such authenticated responses also need the public cache |
| 6636 | | control directive in order to allow them to be cached at all. |
| 6637 | | </t></list> |
| 6638 | | </t> |
| 6639 | | </section> |
| 6640 | | |
| 6641 | | <section title="No-Transform Directive" anchor="no-transform.directive"> |
| 6642 | | <t> |
| 6643 | | <iref item="Cache Directives" subitem="no-transform" primary="true"/> |
| 6644 | | <iref item="no-transform" subitem="Cache Directive" primary="true"/> |
| 6645 | | no-transform |
| 6646 | | <list><t> |
| 6647 | | Implementors of intermediate caches (proxies) have found it useful |
| 6648 | | to convert the media type of certain entity bodies. A non-transparent |
| 6649 | | proxy might, for example, convert between image |
| 6650 | | formats in order to save cache space or to reduce the amount of |
| 6651 | | traffic on a slow link. |
| 6652 | | </t><t> |
| 6653 | | Serious operational problems occur, however, when these |
| 6654 | | transformations are applied to entity bodies intended for certain |
| 6655 | | kinds of applications. For example, applications for medical |
| 6656 | | imaging, scientific data analysis and those using end-to-end |
| 6657 | | authentication, all depend on receiving an entity body that is bit |
| 6658 | | for bit identical to the original entity-body. |
| 6659 | | </t><t> |
| 6660 | | Therefore, if a message includes the no-transform directive, an |
| 6661 | | intermediate cache or proxy &MUST-NOT; change those headers that are |
| 6662 | | listed in <xref target="non-modifiable.headers"/> as being subject to the no-transform |
| 6663 | | directive. This implies that the cache or proxy &MUST-NOT; change |
| 6664 | | any aspect of the entity-body that is specified by these headers, |
| 6665 | | including the value of the entity-body itself. |
| 6666 | | </t></list> |
| 6667 | | </t> |
| 6668 | | </section> |
| 6669 | | |
| 6670 | | <section title="Cache Control Extensions" anchor="cache.control.extensions"> |
| 6671 | | <t> |
| 6672 | | The Cache-Control header field can be extended through the use of one |
| 6673 | | or more cache-extension tokens, each with an optional assigned value. |
| 6674 | | Informational extensions (those which do not require a change in |
| 6675 | | cache behavior) &MAY; be added without changing the semantics of other |
| 6676 | | directives. Behavioral extensions are designed to work by acting as |
| 6677 | | modifiers to the existing base of cache directives. Both the new |
| 6678 | | directive and the standard directive are supplied, such that |
| 6679 | | applications which do not understand the new directive will default |
| 6680 | | to the behavior specified by the standard directive, and those that |
| 6681 | | understand the new directive will recognize it as modifying the |
| 6682 | | requirements associated with the standard directive. In this way, |
| 6683 | | extensions to the cache-control directives can be made without |
| 6684 | | requiring changes to the base protocol. |
| 6685 | | </t> |
| 6686 | | <t> |
| 6687 | | This extension mechanism depends on an HTTP cache obeying all of the |
| 6688 | | cache-control directives defined for its native HTTP-version, obeying |
| 6689 | | certain extensions, and ignoring all directives that it does not |
| 6690 | | understand. |
| 6691 | | </t> |
| 6692 | | <t> |
| 6693 | | For example, consider a hypothetical new response directive called |
| 6694 | | community which acts as a modifier to the private directive. We |
| 6695 | | define this new directive to mean that, in addition to any non-shared |
| 6696 | | cache, any cache which is shared only by members of the community |
| 6697 | | named within its value may cache the response. An origin server |
| 6698 | | wishing to allow the UCI community to use an otherwise private |
| 6699 | | response in their shared cache(s) could do so by including |
| 6700 | | </t> |
| 6701 | | <figure><artwork type="example"> |
| 6702 | | Cache-Control: private, community="UCI" |
| 6703 | | </artwork></figure> |
| 6704 | | <t> |
| 6705 | | A cache seeing this header field will act correctly even if the cache |
| 6706 | | does not understand the community cache-extension, since it will also |
| 6707 | | see and understand the private directive and thus default to the safe |
| 6708 | | behavior. |
| 6709 | | </t> |
| 6710 | | <t> |
| 6711 | | Unrecognized cache-directives &MUST; be ignored; it is assumed that any |
| 6712 | | cache-directive likely to be unrecognized by an HTTP/1.1 cache will |
| 6713 | | be combined with standard directives (or the response's default |
| 6714 | | cacheability) such that the cache behavior will remain minimally |
| 6715 | | correct even if the cache does not understand the extension(s). |
| 6716 | | </t> |
| 6717 | | </section> |
| 6718 | | </section> |
![(please configure the [header_logo] section in trac.ini)](https://www.ietf.org/images/ietflogotrans.gif)