Changeset 1223 for draft-ietf-httpbis/latest/p4-conditional.xml
- Timestamp:
- 28/03/11 14:15:02 (11 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
draft-ietf-httpbis/latest/p4-conditional.xml
r1180 r1223 225 225 </t> 226 226 <t> 227 We use the term "selected representation" to refer to the current 228 representation of the target resource that would have been selected 229 and sent as payload in a 200 (OK) response if the same request had used 230 the method GET and had excluded all of the conditional request header 231 fields. The conditions found within conditional requests are evaluated 232 on the basis of either the state of the target resource as a whole or 233 the state of the target resource's selected representation. 234 </t> 235 <t> 227 236 This document is currently disorganized in order to minimize the changes 228 237 between drafts and enable reviewers to see the smaller errata changes. … … 329 338 <t> 330 339 A "weak entity-tag", indicated by the "W/" prefix, &MAY; be shared by 331 two representations of a resource only if the representations are equivalent and 332 could be substituted for each other with no significant change in 333 semantics. A weak entity-tag can only be used for weak comparison. 334 </t> 335 <t> 336 An entity-tag &MUST; be unique across all versions of all representations 337 associated with a particular resource. A given entity-tag value &MAY; 338 be used for representations obtained by requests on different URIs. The use 339 of the same entity-tag value in conjunction with representations obtained by 340 requests on different URIs does not imply the equivalence of those 341 representations. 340 two representations of a resource. A weak entity-tag can only be used 341 for weak comparison. 342 </t> 343 <t> 344 Cache entries might persist for arbitrarily long periods, regardless 345 of expiration times, so it is inappropriate to expect that a cache will 346 never again attempt to validate an entry using a validator that it 347 obtained at some point in the past. 348 A strong entity-tag &MUST; be unique across all versions of all 349 representations associated with a particular resource over time. 350 However, there is no implication of uniqueness across entity-tags 351 of different resources (i.e., the same entity-tag value might be 352 in use for representations of multiple resources at the same time 353 and does not imply that those representations are equivalent). 342 354 </t> 343 355 … … 402 414 <iref primary="true" item="Status Codes" subitem="304 Not Modified" x:for-anchor=""/> 403 415 <t> 404 If the client has performed a conditional GET request and access is 405 allowed, but the document has not been modified, the server &SHOULD; 406 respond with this status code. The 304 response &MUST-NOT; contain a 407 message-body, and thus is always terminated by the first empty line 408 after the header fields. 416 The 304 status code indicates that a conditional GET request has been 417 received and would have resulted in a 200 (OK) response if it were not 418 for the fact that the condition has evaluated to false. In other words, 419 there is no need for the server to transfer a representation of the 420 target resource because the client's request indicates that it already 421 has a valid representation, as indicated by the 304 response header 422 fields, and is therefore redirecting the client to make use of that 423 stored representation as if it were the payload of a 200 response. 424 The 304 response &MUST-NOT; contain a message-body, and thus is always 425 terminated by the first empty line after the header fields. 409 426 </t> 410 427 <t> … … 423 440 </t> 424 441 <t> 425 If a 304 response includes an entity-tag that indicates a 426 representation not currently cached, then the recipient &MUST-NOT; 427 use the 304 to update its own cache. If that conditional request originated 428 with an outbound client, such as a user agent with its own cache sending a 429 conditional GET to a shared proxy, then the 304 response &MAY; be 430 forwarded to the outbound client. Otherwise, disregard the response 431 and repeat the request without the conditional. 442 If the recipient of a 304 response does not have a cached representation 443 corresponding to the entity-tag indicated by the 304 response, then the 444 recipient &MUST-NOT; use the 304 to update its own cache. If this 445 conditional request originated with an outbound client, such as a 446 user agent with its own cache sending a conditional GET to a shared 447 proxy, then the 304 response &MAY; be forwarded to the outbound client. 448 Otherwise, the recipient &MUST; disregard the 304 response and repeat 449 the request without any preconditions. 432 450 </t> 433 451 <t> … … 442 460 <iref primary="true" item="Status Codes" subitem="412 Precondition Failed" x:for-anchor=""/> 443 461 <t> 444 The precondition given in one or more of the header fields 445 evaluated to false when it was tested on the server. This response 446 code allows the client to place preconditions on the current resource 447 metadata (header field data) and thus prevent the requested 448 method from being applied to a resource other than the one intended. 462 The 412 status code indicates that one or more preconditions given in 463 the request header fields evaluated to false when tested on the server. 464 This response code allows the client to place preconditions on the 465 current resource state (its current representations and metadata) 466 and thus prevent the request method from being applied if the target 467 resource is in an unexpected state. 449 468 </t> 450 469 </section> … … 454 473 <t> 455 474 Since both origin servers and caches will compare two validators to 456 decide if they represent the same or different representations, one normally 457 would expect that if the representation (including both representation 458 header fields and representation body) changes in any way, then the 459 associated validator would change as well. If this is true, then we 460 call this validator a "strong validator". 475 decide if they represent the same or different representations, one 476 normally would expect that if the representation (including both 477 representation header fields and representation body) changes in any 478 way, then the associated validator would change as well. If this is 479 true, then we call this validator a "strong validator". One example 480 of a strong validator is an integer that is incremented in stable 481 storage every time a representation is changed. 461 482 </t> 462 483 <t> 463 484 However, there might be cases when a server prefers to change the 464 validator only on semantically significant changes, and not when 465 insignificant aspects of the representation change. A validator that does not 466 always change when the representation changes is a "weak validator". 485 validator only when it desires cached representations to be invalidated. 486 For example, the representation of a weather report that changes in 487 content every second, based on dynamic measurements, might be grouped 488 into sets of equivalent representations (from the origin server's 489 perspective) in order to allow cached representations to be valid 490 for a reasonable period of time (perhaps adjusted dynamically based 491 on server load or weather quality). 492 A validator that does not always change when the representation 493 changes is a "weak validator". 467 494 </t> 468 495 <t> 469 496 An entity-tag is normally a strong validator, but the protocol 470 provides a mechanism to tag an entity-tag as "weak". One can think of 471 a strong validator as one that changes whenever the sequence of bits 472 in a representation changes, while a weak value changes whenever the 473 meaning of a representation changes. Alternatively, one can think of 474 a strong validator as part of an identifier for a specific representation, 475 whereas a weak validator is part of an identifier for a set of semantically 476 equivalent representations. 497 provides a mechanism to tag an entity-tag as "weak". One can think 498 of a strong validator as part of an identifier for a specific 499 representation, whereas a weak validator is part of an identifier 500 for a set of equivalent representations (where this notion of 501 equivalence is entirely governed by the origin server and beyond 502 the scope of this specification). 477 503 <list><t> 478 <x:h>Note:</x:h> One example of a strong validator is an integer that is479 incremented in stable storage every time a representation is changed.480 </t><t>481 504 A representation's modification time, if defined with only one-second 482 505 resolution, could be a weak validator, since it is possible that … … 491 514 </t> 492 515 <t> 516 A strong entity-tag &MUST; change whenever the associated representation 517 changes in any way. A weak entity-tag &SHOULD; change whenever the origin 518 server considers prior representations to be unacceptable as a substitute 519 for the current representation. In other words, a weak entity tag &SHOULD; 520 change whenever the origin server wants caches to invalidate old responses. 521 </t> 522 <t> 493 523 A "use" of a validator is either when a client generates a request 494 524 and includes the validator in a validating header field, or when a … … 499 529 usable in contexts that do not depend on exact equality of a representation. 500 530 For example, either kind is usable for a normal conditional GET. 501 However, only a strong validator is usable for a sub-range 502 retrieval, since otherwise the client might end up with an internally 503 inconsistent representation. 504 </t> 505 <t> 506 Clients &MUST-NOT; use weak validators in range requests (<xref target="Part5"/>). 531 However, only a strong validator is usable for range retrieval 532 (<xref target="Part5"/>), since otherwise the client might end up 533 with an internally inconsistent representation. 534 Clients &MUST-NOT; use weak validators in range requests. 507 535 </t> 508 536 <t> … … 635 663 or if it is unfeasible to send a strong entity-tag.</t> 636 664 637 <t>&SHOULD; send a Last-Modified value if it is feasible to send one, 638 unless the risk of a breakdown in semantic transparency that 639 could result from using this date in an If-Modified-Since header 640 field would lead to serious problems.</t> 665 <t>&SHOULD; send a Last-Modified value if it is feasible to send one.</t> 641 666 </list> 642 667 </t> … … 645 670 is to send both a strong entity-tag and a Last-Modified value. 646 671 </t> 647 <t>648 In order to be legitimate, a strong entity-tag &MUST; change whenever the649 associated representation changes in any way. A weak entity-tag &SHOULD;650 change whenever the associated representation changes in a semantically651 significant way.652 </t>653 <x:note>654 <t>655 <x:h>Note:</x:h> In order to provide semantically transparent caching, an656 origin server must avoid reusing a specific strong entity-tag657 value for two different representations, or reusing a specific weak658 entity-tag value for two semantically different representations. Cache659 entries might persist for arbitrarily long periods, regardless of660 expiration times, so it might be inappropriate to expect that a661 cache will never again attempt to validate an entry using a662 validator that it obtained at some point in the past.663 </t>664 </x:note>665 672 <t> 666 673 HTTP/1.1 clients: … … 774 781 <x:anchor-alias value="If-Match-v"/> 775 782 <t> 776 The "If-Match" header field is used to make a request method 777 conditional. A client that has one or more representations previously 778 obtained from the resource can verify that one of those representations is 779 current by including a list of their associated entity-tags in the 780 If-Match header field. 781 </t> 782 <t> 783 This allows efficient updates of cached information with a minimum amount of 784 transaction overhead. It is also used when updating resources, to prevent 785 inadvertent modification of the wrong version of a resource. As a special 786 case, the value "*" matches any current representation of the resource. 783 The "If-Match" header field &MAY; be used to make a request method 784 conditional on the current existence or value of an entity-tag for 785 one or more representations of the target resource. If-Match is 786 generally useful for resource update requests, such as PUT requests, 787 as a means for protecting against accidental overwrites when multiple 788 clients are acting in parallel on the same resource (i.e., the 789 "lost update" problem). An If-Match field-value of "*" places the 790 precondition on the existence of any current representation for the 791 target resource. 787 792 </t> 788 793 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="If-Match"/><iref primary="true" item="Grammar" subitem="If-Match-v"/> … … 791 796 </artwork></figure> 792 797 <t> 793 If any of the entity-tags match the entity-tag of the representation that 794 would have been returned in the response to a similar GET request 795 (without the If-Match header field) on that resource, or if "*" is given 796 and any current representation exists for that resource, then the server &MAY; 797 perform the requested method as if the If-Match header field did not 798 exist. 798 If any of the entity-tags listed in the If-Match field value match 799 the entity-tag of the selected representation for the target resource, 800 or if "*" is given and any current representation exists for the 801 target resource, then the server &MAY; perform the request method 802 as if the If-Match header field was not present. 799 803 </t> 800 804 <t> 801 805 If none of the entity-tags match, or if "*" is given and no current 802 representation exists, the server &MUST-NOT; perform the requested method, and 803 &MUST; return a 412 (Precondition Failed) response. This behavior is 804 most useful when the client wants to prevent an updating request method, 805 such as PUT, from modifying a resource that has changed since the client 806 last retrieved it. 806 representation exists, the server &MUST-NOT; perform the requested method. 807 Instead, the server &MUST; respond with the 412 (Precondition Failed) 808 status code. 807 809 </t> 808 810 <t> … … 812 814 </t> 813 815 <t> 814 The meaning of "If-Match: *" is that the request method &SHOULD; be performed815 if the representation selected by the origin server (or by a cache,816 possibly using the Vary mechanism, see &header-vary;) exists, and817 &MUST-NOT; be performed if the representation does not exist.818 </t>819 <t>820 A request intended to update a resource (e.g., a PUT) &MAY; include an821 If-Match header field to signal that the request method &MUST-NOT; be822 applied if the representation corresponding to the If-Match value (a single823 entity-tag) is no longer a representation of that resource. This824 allows the user to indicate that they do not wish the request to be825 successful if the resource has been changed without their knowledge.826 816 Examples: 827 817 </t> … … 844 834 <x:anchor-alias value="If-Modified-Since-v"/> 845 835 <t> 846 The "If-Modified-Since" header field is used to make a request 847 method conditional by date: if the representation that would have been 848 transferred in a 200 response to a GET request has not been modified since 849 the time specified in this field, then do not perform the method; 850 instead, respond as detailed below. 836 The "If-Modified-Since" header field &MAY; be used to make a request 837 method conditional by modification date: if the selected representation 838 has not been modified since the time specified in this field, then 839 do not perform the request method; instead, respond as detailed below. 851 840 </t> 852 841 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="If-Modified-Since"/><iref primary="true" item="Grammar" subitem="If-Modified-Since-v"/> … … 863 852 <t> 864 853 A GET method with an If-Modified-Since header field and no Range header 865 field requests that the representation be transferred only if it has 866 been modified since the date given by the If-Modified-Since header field. 854 field requests that the selected representation be transferred only if 855 it has been modified since the date given by the If-Modified-Since 856 header field. 867 857 The algorithm for determining this includes the following cases: 868 858 <list style="numbers"> … … 873 863 invalid.</t> 874 864 875 <t>If the representation has been modified since the If-Modified-Since 876 date, the response is exactly the same as for a normal GET.</t> 877 878 <t>If the representation has not been modified since a valid 865 <t>If the selected representation has been modified since the 866 If-Modified-Since date, the response is exactly the same as for 867 a normal GET.</t> 868 869 <t>If the selected representation has not been modified since a valid 879 870 If-Modified-Since date, the server &SHOULD; return a 880 871 304 (Not Modified) response.</t> … … 929 920 <x:anchor-alias value="If-None-Match-v"/> 930 921 <t> 931 The "If-None-Match" header field is used to make a request method 932 conditional. A client that has one or more representations previously 933 obtained from the resource can verify that none of those representations is 934 current by including a list of their associated entity-tags in the 935 If-None-Match header field. 936 </t> 937 <t> 938 This allows efficient updates of cached information with a minimum amount of 939 transaction overhead. It is also used to prevent a request method (e.g., PUT) 940 from inadvertently modifying an existing resource when the client 941 believes that the resource does not exist. 942 </t> 943 <t> 944 As a special case, the value "*" matches any current representation of the 945 resource. 922 The "If-None-Match" header field &MAY; be used to make a request method 923 conditional on not matching any of the current entity-tag values for 924 representations of the target resource. If-None-Match is primarily 925 used in conditional GET requests to enable efficient updates of cached 926 information with a minimum amount of transaction overhead. A client 927 that has one or more representations previously obtained from the 928 target resource can send If-None-Match with a list of the associated 929 entity-tags in the hope of receiving a 304 response if at least one 930 of those representations matches the selected representation. 931 </t> 932 <t> 933 If-None-Match MAY also be used with a value of "*" to prevent an unsafe 934 request method (e.g., PUT) from inadvertently modifying an existing 935 representation of the target resource when the client believes that 936 the resource does not have a current representation. This is a variation 937 on the "lost update" problem that might arise if more than one client 938 attempts to create an initial representation for the target resource. 946 939 </t> 947 940 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="If-None-Match"/><iref primary="true" item="Grammar" subitem="If-None-Match-v"/> … … 950 943 </artwork></figure> 951 944 <t> 952 If any of the entity-tags match the entity-tag of the representation that 953 would have been returned in the response to a similar GET request 954 (without the If-None-Match header field) on that resource, or if "*" is 945 If any of the entity-tags listed in the If-None-Match field-value match 946 the entity-tag of the selected representation, or if "*" is 955 947 given and any current representation exists for that resource, then the 956 server &MUST-NOT; perform the requested method, unless required to do 957 so because the resource's modification date fails to match that 958 supplied in an If-Modified-Since header field in the request. 948 server &MUST-NOT; perform the requested method. 959 949 Instead, if the request method was GET or HEAD, the server &SHOULD; 960 respond with a 304 (Not Modified) response, including the cache-related961 header fields (particularly ETag) of one of the representations that962 matched. For all other request methods, the server &MUST; respond with963 a 412 (Precondition Failed) status code.950 respond with a 304 (Not Modified) status code, including the cache-related 951 header fields (particularly ETag) of the selected representation that has 952 a matching entity-tag. For all other request methods, the server &MUST; 953 respond with a 412 (Precondition Failed) status code. 964 954 </t> 965 955 <t> … … 973 963 If the request would, without the If-None-Match header field, result 974 964 in anything other than a 2xx or 304 status code, then the If-None-Match 975 header field &MUST; be ignored. (See <xref target="rules.for.when.to.use.entity.tags.and.last-modified.dates"/> for a discussion of 976 server behavior when both If-Modified-Since and If-None-Match appear 977 in the same request.) 978 </t> 979 <t> 980 The meaning of "If-None-Match: *" is that the request method &MUST-NOT; be 981 performed if the representation selected by the origin server (or by 982 a cache, possibly using the Vary mechanism, see &header-vary;) 983 exists, and &SHOULD; be performed if the representation does not exist. 984 This feature is intended to be useful in preventing races between PUT 985 operations. 965 header field &MUST; be ignored. (See <xref 966 target="rules.for.when.to.use.entity.tags.and.last-modified.dates"/> for 967 a discussion of server behavior when both If-Modified-Since and 968 If-None-Match appear in the same request.) 986 969 </t> 987 970 <t> … … 1008 991 <x:anchor-alias value="If-Unmodified-Since-v"/> 1009 992 <t> 1010 The "If-Unmodified-Since" header field is used to make a request 1011 method conditional. If the representation that would have been transferred 1012 in a 200 response to a GET request on the same resource has not been modified 1013 since the time specified in this field, the server &SHOULD; perform the 1014 requested operation as if the If-Unmodified-Since header field were not 1015 present. 1016 </t> 1017 <t> 1018 If the representation has been modified since the specified time, 1019 the server &MUST-NOT; perform the requested operation, and &MUST; return 1020 a 412 (Precondition Failed). 993 The "If-Unmodified-Since" header field &MAY; be used to make a request 994 method conditional by modification date: if the selected representation 995 has been modified since the time specified in this field, then the 996 server &MUST-NOT; perform the requested operation and &MUST; instead 997 respond with the 412 (Precondition Failed) status code. 998 If the selected representation has not been modified since the time 999 specified in this field, the server &SHOULD; perform the request 1000 method as if the If-Unmodified-Since header field were not present. 1021 1001 </t> 1022 1002 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="If-Unmodified-Since"/><iref primary="true" item="Grammar" subitem="If-Unmodified-Since-v"/> … … 1037 1017 </t> 1038 1018 <t> 1039 If the specified date is invalid, the header field isignored.1019 If the specified date is invalid, the header field &MUST; be ignored. 1040 1020 </t> 1041 1021 <t>
Note: See TracChangeset
for help on using the changeset viewer.