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> |