Changeset 2057 for draft-ietf-httpbis/latest/p2-semantics.xml
- Timestamp:
- 27/12/12 15:58:30 (10 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
draft-ietf-httpbis/latest/p2-semantics.xml
r2056 r2057 718 718 <t>If the request is GET or HEAD and the response status code is 719 719 <x:ref>203 (Non-Authoritative Information)</x:ref>, the payload is a 720 potentially modified representation of the target resource; as such,721 the effective request URI might only act as an identifier for the722 payload's representation when a request is made via the same chain723 of intermediaries.</t>720 potentially modified representation of the 721 <x:ref>target resource</x:ref>; as such, the effective request URI 722 might only act as an identifier for the payload's representation when 723 a request is made via the same chain of intermediaries.</t> 724 724 <t>If the response has a <x:ref>Content-Location</x:ref> header field 725 725 and its field-value is a reference to the same URI as the effective … … 864 864 <t> 865 865 For example, a representation in the payload of a PUT request 866 (<xref target="PUT"/>) represents the desired state of the target resource866 (<xref target="PUT"/>) represents the desired state of the <x:ref>target resource</x:ref> 867 867 if the request is successfully applied, whereas a representation in the 868 868 payload of a POST request (<xref target="POST"/>) represents an anonymous … … 872 872 <t> 873 873 Likewise, the payload of a <x:ref>200 (OK)</x:ref> response to GET 874 (<xref target="GET"/>) contains a representation of the target resource,874 (<xref target="GET"/>) contains a representation of the <x:ref>target resource</x:ref>, 875 875 as observed at the time of the message origination date 876 876 (<xref target="header.date"/>), whereas the same status code in a response … … 940 940 (a.k.a., <x:dfn>server-driven negotiation</x:dfn>). Selection is based on 941 941 the available representations for a response (the dimensions over which it 942 might vary ; e.g.,language, content-coding, etc.) compared to various942 might vary, such as language, content-coding, etc.) compared to various 943 943 information supplied in the request, including both the explicit 944 944 negotiation fields of <xref target="request.conneg"/> and implicit … … 1056 1056 HTTP was originally designed to be usable as an interface to distributed 1057 1057 object systems. The request method was envisioned as applying 1058 semantics to a target resourcein much the same way as invoking a defined1058 semantics to a <x:ref>target resource</x:ref> in much the same way as invoking a defined 1059 1059 method on an identified object would apply semantics. The method token 1060 1060 is case-sensitive because it might be used as a gateway to object-based … … 1239 1239 <t> 1240 1240 The GET method requests transfer of a current representation of 1241 the target resource.1241 the <x:ref>target resource</x:ref>. 1242 1242 </t> 1243 1243 <t> … … 1313 1313 The POST method requests that the origin server accept the 1314 1314 representation enclosed in the request as data to be processed by the 1315 target resource. For example, POST is frequently used for the following1315 <x:ref>target resource</x:ref>. For example, POST is frequently used for the following 1316 1316 functions (among others): 1317 1317 <list style="symbols"> … … 1370 1370 <iref primary="true" item="PUT method" x:for-anchor=""/> 1371 1371 <t> 1372 The PUT method requests that the state of the target resource1372 The PUT method requests that the state of the <x:ref>target resource</x:ref> 1373 1373 be created or replaced with the state defined by the representation 1374 1374 enclosed in the request message payload. A successful PUT of a given … … 1498 1498 <t> 1499 1499 The DELETE method requests that the origin server remove the association 1500 between the target resourceand its current representations or1500 between the <x:ref>target resource</x:ref> and its current representations or 1501 1501 implementation. In effect, this method is similar to the rm command in 1502 1502 UNIX: it expresses a deletion operation on the URI mapping of the … … 1936 1936 <t> 1937 1937 Conditionals are request header fields that indicate a precondition to be 1938 tested before applying the method semantics to the target resource.1938 tested before applying the method semantics to the <x:ref>target resource</x:ref>. 1939 1939 Each precondition is based on metadata that is expected to change if the 1940 1940 selected representation of the target resource is changed. The HTTP/1.1 … … 2671 2671 <list style="hanging"> 2672 2672 <t hangText="GET"> 2673 a representation of the target resource is sent in the response;2673 a representation of the <x:ref>target resource</x:ref>; 2674 2674 </t> 2675 2675 <t hangText="HEAD"> … … 2763 2763 has successfully fulfilled the request and that there is no additional 2764 2764 content to send in the response payload body. Metadata in the response 2765 header fields refer to the target resourceand its current representation2765 header fields refer to the <x:ref>target resource</x:ref> and its current representation 2766 2766 after the requested action. 2767 2767 </t> … … 2911 2911 <t> 2912 2912 The <x:dfn>300 (Multiple Choices)</x:dfn> status code indicates that the 2913 target resourcehas more than one representation, each with its own more2913 <x:ref>target resource</x:ref> has more than one representation, each with its own more 2914 2914 specific identifier, and information about the alternatives is being 2915 2915 provided so that the user (or user agent) can select a preferred … … 2946 2946 <t> 2947 2947 The <x:dfn>301 (Moved Permanently)</x:dfn> status code indicates that the 2948 target resource has been assigned a new permanent URI and any future2949 references to this resource ought to use one of the enclosed URIs. Clients2950 with link editing capabilities ought to automatically re-link references to2951 the effective request URI to one or more of the new references sent by the2952 server, where possible.2948 <x:ref>target resource</x:ref> has been assigned a new permanent URI and 2949 any future references to this resource ought to use one of the enclosed 2950 URIs. Clients with link editing capabilities ought to automatically re-link 2951 references to the effective request URI to one or more of the new 2952 references sent by the server, where possible. 2953 2953 </t> 2954 2954 <t> … … 3023 3023 </t> 3024 3024 <t> 3025 A 303 response to a GET request indicates that the requested3026 resource does not have a representation of its own that can be3027 transferred by the server over HTTP. The <x:ref>Location</x:ref> URI3028 indicates a resource that is descriptive of the target resource, such that3029 the follow-on representation might be useful to recipients without3030 implying that it adequately represents the target resource.3031 Note that answers to the questions of what can be represented, what3032 represent ations are adequate, and what might be a useful description3033 are outside the scope of HTTP and thus entirely determined by the3034 URI owner(s).3025 A 303 response to a GET request indicates that the 3026 <x:ref>target resource</x:ref> resource does not have a representation of 3027 its own that can be transferred by the server over HTTP. 3028 The <x:ref>Location</x:ref> URI identifies a resource that is descriptive 3029 of the target resource, such that the follow-on representation might be 3030 useful to recipients without implying that it adequately represents the 3031 target resource. Note that answers to the questions of what can be 3032 represented, what representations are adequate, and what might be a useful 3033 description are outside the scope of HTTP and thus entirely determined by 3034 the URI owner(s). 3035 3035 </t> 3036 3036 <t> … … 3065 3065 <t> 3066 3066 The <x:dfn>307 (Temporary Redirect)</x:dfn> status code indicates that the 3067 target resource resides temporarily under a different URI and the3068 user agent &MUST-NOT; change the request method if it performs an automatic3069 redirection to that URI.3067 <x:ref>target resource</x:ref> resides temporarily under a different URI 3068 and the user agent &MUST-NOT; change the request method if it performs an 3069 automatic redirection to that URI. 3070 3070 Since the redirection can change over time, the client ought to continue 3071 3071 using the original effective request URI for future requests. … … 3108 3108 <x:anchor-alias value="400 (Bad Request)"/> 3109 3109 <t> 3110 The server cannot or will not process the request, due to a client error (e.g., 3111 malformed syntax). 3110 The <x:dfn>400 (Bad Request)</x:dfn> status code indicates that the server 3111 cannot or will not process the request because the received syntax is 3112 invalid, nonsensical, or exceeds some limitation on what the server is 3113 willing to process. 3112 3114 </t> 3113 3115 </section> … … 3126 3128 <x:anchor-alias value="403 (Forbidden)"/> 3127 3129 <t> 3128 The server understood the request, but refuses to authorize it. Providing 3129 different user authentication credentials might be successful, but any 3130 credentials that were provided in the request are insufficient. The request 3131 &SHOULD-NOT; be repeated with the same credentials. 3132 </t> 3133 <t> 3134 If the request method was not HEAD and the server wishes to make 3135 public why the request has not been fulfilled, it &SHOULD; describe the 3136 reason for the refusal in the representation. If the server does not wish to 3137 make this information available to the client, the status code <x:ref>404 3138 (Not Found)</x:ref> &MAY; be used instead. 3130 The <x:dfn>403 (Forbidden)</x:dfn> status code indicates that the origin 3131 server understood the request but refuses to authorize it. 3132 A server that wishes to make public why the request has been forbidden 3133 can describe that reason in the response payload (if any). 3134 </t> 3135 <t> 3136 If authentication credentials were provided in the request, the origin 3137 server considers them insufficient to grant access. 3138 The client &SHOULD-NOT; repeat the request with the same credentials. 3139 The client &MAY; repeat the request with new or different credentials. 3140 However, a request might be forbidden for reasons unrelated to the 3141 credentials. 3142 </t> 3143 <t> 3144 An origin server that wishes to "hide" the current existence of a forbidden 3145 <x:ref>target resource</x:ref> &MAY; instead respond with a status 3146 code of <x:ref>404 (Not Found)</x:ref>. 3139 3147 </t> 3140 3148 </section> … … 3144 3152 <x:anchor-alias value="404 (Not Found)"/> 3145 3153 <t> 3146 The server has not found anything matching the effective request URI. No 3147 indication is given of whether the condition is temporary or 3148 permanent. The <x:ref>410 (Gone)</x:ref> status code &SHOULD; be used if the server 3149 knows, through some internally configurable mechanism, that an old 3150 resource is permanently unavailable and has no forwarding address. 3151 This status code is commonly used when the server does not wish to 3152 reveal exactly why the request has been refused, or when no other 3153 response is applicable. 3154 The <x:dfn>404 (Not Found)</x:dfn> status code indicates that the origin 3155 server did not find a current representation for the 3156 <x:ref>target resource</x:ref> or is not willing to disclose that one 3157 exists. A 404 status does not indicate whether this lack of representation 3158 is temporary or permanent; the <x:ref>410 (Gone)</x:ref> status code is 3159 preferred over 404 if the origin server knows, presumably through some 3160 configurable means, that the condition is likely to be permanent. 3154 3161 </t> 3155 3162 </section> … … 3159 3166 <x:anchor-alias value="405 (Method Not Allowed)"/> 3160 3167 <t> 3161 The method specified in the request-line is not allowed for the target 3162 resource. The response &MUST; include an <x:ref>Allow</x:ref> header field 3163 containing a list of valid methods for the requested resource. 3168 The <x:dfn>405 (Method Not Allowed)</x:dfn> status code indicates that the 3169 method specified in the request-line is not allowed by the origin server 3170 for the <x:ref>target resource</x:ref>. The origin server &MUST; generate 3171 an <x:ref>Allow</x:ref> header field in the response containing a list of 3172 valid methods for the requested resource. 3164 3173 </t> 3165 3174 </section> … … 3169 3178 <x:anchor-alias value="406 (Not Acceptable)"/> 3170 3179 <t> 3171 The resource identified by the request is only capable of generating 3172 response representations which have content characteristics not acceptable 3173 according to the <x:ref>Accept</x:ref> and Accept-* header fields sent in 3174 the request. 3175 </t> 3176 <t> 3177 Unless it was a HEAD request, the response &SHOULD; include a representation 3178 containing a list of available representation characteristics and location(s) 3179 from which the user or user agent can choose the one most 3180 appropriate. Depending upon the format and the 3181 capabilities of the user agent, selection of the most appropriate 3182 choice &MAY; be performed automatically. However, this specification 3183 does not define any standard for such automatic selection. 3184 </t> 3185 <x:note> 3186 <t> 3187 &Note; HTTP/1.1 servers are allowed to send responses which are 3188 not acceptable according to the accept header fields sent in the 3189 request. In some cases, this might even be preferable to sending a 3190 406 response. User agents are encouraged to inspect the header fields of 3191 an incoming response to determine if it is acceptable. 3192 </t> 3193 </x:note> 3194 <t> 3195 If the response could be unacceptable, a user agent &SHOULD; 3196 temporarily stop receipt of more data and query the user for a 3197 decision on further actions. 3180 The <x:dfn>406 (Not Acceptable)</x:dfn> status code indicates that the 3181 <x:ref>target resource</x:ref> does not have a current representation which 3182 would be acceptable to the user agent, according to the 3183 <x:ref>proactive negotiation</x:ref> header fields received in the request 3184 (<xref target="request.conneg"/>), and the server is unwilling to supply a 3185 default representation. 3186 </t> 3187 <t> 3188 The server &SHOULD; generate a payload containing a list of available 3189 representation characteristics and corresponding resource identifiers from 3190 which the user or user agent can choose the one most appropriate. 3191 A user agent &MAY; automatically select the most appropriate choice from 3192 that list. However, this specification does not define any standard for 3193 such automatic selection. [The original proposal for 406 defined the 3194 Alternates header field as providing a list of alternative representations, 3195 such that it would be available for responses to the HEAD method, but lack 3196 of deployment led to Alternates being dropped from the specification.] 3198 3197 </t> 3199 3198 </section> … … 3201 3200 <section title="408 Request Timeout" anchor="status.408"> 3202 3201 <iref primary="true" item="408 Request Timeout (status code)" x:for-anchor=""/> 3203 <t> 3204 The server did not receive a complete request message within the time that 3205 it was prepared to wait. If the client has sent a request, it &MAY; repeat 3206 that request, possibly on a new connection if the server indicates that the 3207 present connection is being closed. 3202 <x:anchor-alias value="408 (Request Timeout)"/> 3203 <t> 3204 The <x:dfn>408 (Request Timeout)</x:dfn> status code indicates 3205 that the server did not receive a complete request message within the time 3206 that it was prepared to wait. Since the only reason to send this message 3207 is if the server has decided to close the connection, the server &SHOULD; 3208 indicate that intent with the <x:ref>close</x:ref> connection option 3209 (&header-connection;). If the client has an outstanding request in transit, 3210 the client &MAY; repeat that request on a new connection. 3208 3211 </t> 3209 3212 </section> … … 3213 3216 <x:anchor-alias value="409 (Conflict)"/> 3214 3217 <t> 3215 The request could not be completed due to a conflict with the current3216 state of the resource. This code is only allowed in situations where3217 it is expected that the user might be able to resolve the conflict3218 and resubmit the request. The payload &SHOULD; include enough3219 information for the user to recognize the source of the conflict.3220 Ideally, the response representation would include enough information for the3221 user or user agent to fix the problem; however, that might not be3222 possible and is not required.3218 The <x:dfn>409 (Conflict)</x:dfn> status code indicates that the request 3219 could not be completed due to a conflict with the current state of the 3220 resource. This code is only reasonable in situations where it is expected 3221 that the user might be able to resolve the conflict and resubmit the 3222 request. The server &SHOULD; generate a payload that includes enough 3223 information for the user to recognize the source of the conflict. Ideally, 3224 the response would include enough information for the user or user agent to 3225 fix the problem; however, that might not be possible and is not required. 3223 3226 </t> 3224 3227 <t> … … 3237 3240 <x:anchor-alias value="410 (Gone)"/> 3238 3241 <t> 3239 The target resource is no longer available at the server and no 3240 forwarding address is known. This condition is expected to be 3241 considered permanent. Clients with link editing capabilities &SHOULD; 3242 delete references to the effective request URI after user approval. If the 3243 server does not know, or has no facility to determine, whether or not 3244 the condition is permanent, the status code <x:ref>404 (Not Found)</x:ref> 3245 &SHOULD; be used instead. 3242 The <x:dfn>410 (Gone)</x:dfn> status code indicates that access to the 3243 <x:ref>target resource</x:ref> is no longer available at the origin 3244 server and that this condition is likely to be permanent. If the origin 3245 server does not know, or has no facility to determine, whether or not the 3246 condition is permanent, the status code <x:ref>404 (Not Found)</x:ref> 3247 ought to be used instead. 3246 3248 </t> 3247 3249 <t> … … 3251 3253 remote links to that resource be removed. Such an event is common for 3252 3254 limited-time, promotional services and for resources belonging to 3253 individuals no longer working at theserver's site. It is not3255 individuals no longer associated with the origin server's site. It is not 3254 3256 necessary to mark all permanently unavailable resources as "gone" or 3255 3257 to keep the mark for any length of time — that is left to the … … 3266 3268 <x:anchor-alias value="411 (Length Required)"/> 3267 3269 <t> 3268 The server refuses to accept the request without a defined 3269 <x:ref>Content-Length</x:ref>. The client &MAY; repeat the request if it 3270 adds a valid Content-Length header field containing the length of the 3271 message body in the request message. 3272 </t> 3273 </section> 3274 3275 <section title="413 Request Representation Too Large" anchor="status.413"> 3276 <iref primary="true" item="413 Request Representation Too Large (status code)" x:for-anchor=""/> 3277 <t> 3278 The server is refusing to process a request because the request 3279 representation is larger than the server is willing or able to process. The 3280 server &MAY; close the connection to prevent the client from continuing 3270 The <x:dfn>411 (Length Required)</x:dfn> status code indicates that the 3271 server refuses to accept the request without a defined 3272 <x:ref>Content-Length</x:ref> (&header-content-length;). 3273 The client &MAY; repeat the request if it adds a valid Content-Length 3274 header field containing the length of the message body in the request 3275 message. 3276 </t> 3277 </section> 3278 3279 <section title="413 Request Payload Too Large" anchor="status.413"> 3280 <iref primary="true" item="413 Request Payload Too Large (status code)" x:for-anchor=""/> 3281 <x:anchor-alias value="413 (Request Payload Too Large)"/> 3282 <t> 3283 The <x:dfn>413 (Request Payload Too Large)</x:dfn> status code indicates 3284 that the server is refusing to process a request because the request 3285 payload is larger than the server is willing or able to process. 3286 The server &MAY; close the connection to prevent the client from continuing 3281 3287 the request. 3282 3288 </t> 3283 3289 <t> 3284 If the condition is temporary, the server &SHOULD; include a3285 <x:ref>Retry-After</x:ref> header field to indicate that it is temporary and3286 a fter what time the client &MAY; try again.3290 If the condition is temporary, the server &SHOULD; generate a 3291 <x:ref>Retry-After</x:ref> header field to indicate that it is temporary 3292 and after what time the client &MAY; try again. 3287 3293 </t> 3288 3294 </section> … … 3292 3298 <x:anchor-alias value="414 (URI Too Long)"/> 3293 3299 <t> 3294 The server is refusing to service the request because the effective request URI 3295 is longer than the server is willing to interpret. This rare 3296 condition is only likely to occur when a client has improperly 3297 converted a POST request to a GET request with long query 3298 information, when the client has descended into a URI "black hole" of 3300 The <x:dfn>414 (URI Too Long)</x:dfn> status code indicates that the server 3301 is refusing to service the request because the 3302 request-target (&request-target;) is longer than the server is willing to 3303 interpret. This rare condition is only likely to occur when a client has 3304 improperly converted a POST request to a GET request with long query 3305 information, when the client has descended into a "black hole" of 3299 3306 redirection (e.g., a redirected URI prefix that points to a suffix of 3300 3307 itself), or when the server is under attack by a client attempting to 3301 exploit security holes present in some servers using fixed-length 3302 buffersfor reading or manipulating the request-target.3308 exploit security holes present in some servers using fixed-length buffers 3309 for reading or manipulating the request-target. 3303 3310 </t> 3304 3311 </section> … … 3308 3315 <x:anchor-alias value="415 (Unsupported Media Type)"/> 3309 3316 <t> 3310 The server is refusing to service the request because the request 3311 payload is in a format not supported by this request method on the 3312 target resource. The format problem might be due to the request's 3313 indicated <x:ref>Content-Type</x:ref> or <x:ref>Content-Encoding</x:ref>, 3314 or as a result of inspecting the data directly. 3317 The <x:dfn>415 (Unsupported Media Type)</x:dfn> status code indicates that 3318 the origin server is refusing to service the request because the payload is 3319 in a format not supported by the <x:ref>target resource</x:ref> for this 3320 method. The format problem might be due to the request's indicated 3321 <x:ref>Content-Type</x:ref> or <x:ref>Content-Encoding</x:ref>, or as a 3322 result of inspecting the data directly. 3315 3323 </t> 3316 3324 </section> … … 3320 3328 <x:anchor-alias value="417 (Expectation Failed)"/> 3321 3329 <t> 3322 The expectation given in an <x:ref>Expect</x:ref> header field (see3323 <xref target="header.expect"/>) could not be met by this server, or, if the3324 server is a proxy, the server has unambiguous evidence that the request3325 could not be met by the next-hop server.3330 The <x:dfn>417 (Expectation Failed)</x:dfn> status code indicates that the 3331 expectation given in the request's <x:ref>Expect</x:ref> header field 3332 (<xref target="header.expect"/>) could not be met by at least one of the 3333 inbound servers. 3326 3334 </t> 3327 3335 </section> … … 3331 3339 <x:anchor-alias value="426 (Upgrade Required)"/> 3332 3340 <t> 3333 The request can not be completed without a prior protocol upgrade. This 3334 response &MUST; include an <x:ref>Upgrade</x:ref> header field 3335 (&header-upgrade;) specifying the required protocols. 3341 The <x:dfn>426 (Upgrade Required)</x:dfn> status code indicates that the 3342 server refuses to perform the request using the current protocol but might 3343 be willing to do so after the client upgrades to a different protocol. 3344 The server &MUST; send an <x:ref>Upgrade</x:ref> header field in a 426 3345 response to indicate the required protocol(s) (&header-upgrade;). 3336 3346 </t> 3337 3347 <figure> … … 3346 3356 <x:span anchor="s426body">This service requires use of the HTTP/3.0 protocol. 3347 3357 </x:span></artwork></figure> 3348 <t>3349 The server &SHOULD; include a message body in the 426 response which3350 indicates in human readable form the reason for the error and describes any3351 alternative courses which might be available to the user.3352 </t>3353 3358 </section> 3354 3359 </section> … … 3360 3365 <iref primary="true" item="Status Codes Classes" subitem="5xx Server Error" x:for-anchor=""/> 3361 3366 <t> 3362 Response status codes beginning with the digit "5" indicate cases in3363 whichthe server is aware that it has erred or is incapable of3364 performing the request . Except when responding to a HEAD request, the3367 The <x:dfn>5xx (Server Error)</x:dfn> class of status code indicates that 3368 the server is aware that it has erred or is incapable of 3369 performing the requested method. Except when responding to a HEAD request, the 3365 3370 server &SHOULD; include a representation containing an explanation of the 3366 3371 error situation, and whether it is a temporary or permanent … … 3463 3468 information about the response which cannot be placed in the status-line. 3464 3469 These header fields give information about the server and about 3465 further access to the target resource (&effective-request-uri;).3470 further access to the <x:ref>target resource</x:ref>. 3466 3471 </t> 3467 3472 … … 3792 3797 <t><iref primary="true" item="selected representation"/> 3793 3798 We use the term "<x:dfn>selected representation</x:dfn>" to refer to the 3794 the current representation of a target resourcethat would have been3799 the current representation of the <x:ref>target resource</x:ref> that would have been 3795 3800 selected in a successful response if the same request had used the 3796 3801 method GET and excluded any conditional request header fields. … … 3874 3879 <t> 3875 3880 The remaining response header fields provide more information about 3876 the target resourcefor potential use in later requests.3881 the <x:ref>target resource</x:ref> for potential use in later requests. 3877 3882 </t> 3878 3883 <texttable align="left"> … … 3889 3894 <t> 3890 3895 The "Allow" header field lists the set of methods advertised as 3891 supported by the target resource. The purpose of this field is strictly to3896 supported by the <x:ref>target resource</x:ref>. The purpose of this field is strictly to 3892 3897 inform the recipient of valid request methods associated with the resource. 3893 3898 </t> … … 4254 4259 </c> 4255 4260 <c>413</c> 4256 <c>Request RepresentationToo Large</c>4261 <c>Request Payload Too Large</c> 4257 4262 <c> 4258 4263 <xref target="status.413"/> … … 4813 4818 <seriesInfo name="Internet-Draft" value="draft-ietf-httpbis-p1-messaging-&ID-VERSION;"/> 4814 4819 <x:source href="p1-messaging.xml" basename="p1-messaging"> 4820 <x:defines>close</x:defines> 4815 4821 <x:defines>Connection</x:defines> 4816 4822 <x:defines>Content-Length</x:defines>
Note: See TracChangeset
for help on using the changeset viewer.