Changeset 2067 for draft-ietf-httpbis/latest/p2-semantics.xml
- Timestamp:
- 30/12/12 00:22:16 (10 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
draft-ietf-httpbis/latest/p2-semantics.xml
r2065 r2067 779 779 <list style="symbols"> 780 780 <t>For a response to a GET or HEAD request, this is an indication that the 781 effective request URI identifiesa resource that is subject to content781 effective request URI refers to a resource that is subject to content 782 782 negotiation and the Content-Location field-value is a more specific 783 783 identifier for the selected representation.</t> … … 796 796 </t> 797 797 <t> 798 If Content-Location is included in a request message, then it &MAY; 799 be interpreted by the origin server as an indication of where the 800 user agent originally obtained the content of the enclosed 801 representation (prior to any subsequent modification of the content 802 by that user agent). In other words, the user agent is providing 803 the same representation metadata that it received with the original 804 representation. However, such interpretation &MUST-NOT; be used to 805 alter the semantics of the method requested by the client. For 806 example, if a client makes a PUT request on a negotiated resource 807 and the origin server accepts that PUT (without redirection), then the 808 new set of values for that resource is expected to be consistent with 809 the one representation supplied in that PUT; the Content-Location 810 cannot be used as a form of reverse content selection that 811 identifies only one of the negotiated representations to be updated. 812 If the user agent had wanted the latter semantics, it would have applied 813 the PUT directly to the Content-Location URI. 814 </t> 815 <t> 816 A Content-Location field received in a request message is transitory 817 information that &SHOULD-NOT; be saved with other representation 818 metadata for use in later responses. The Content-Location's value 819 might be saved for use in other contexts, such as within source links 820 or other metadata. 821 </t> 822 <t> 823 A cache cannot assume that a representation with a Content-Location 824 different from the URI used to retrieve it can be used to respond to 825 later requests on that Content-Location URI. 798 A user agent that sends Content-Location in a request message is stating 799 that its value refers to where the user agent originally obtained the 800 content of the enclosed representation (prior to any modifications made by 801 that user agent). In other words, the user agent is providing a back link 802 to the source of the original representation. 803 </t> 804 <t> 805 An origin server that receives a Content-Location field in a request 806 message &MUST; treat the information as transitory request context rather 807 than as metadata to be saved verbatim as part of the representation. 808 An origin server &MAY; use that context to guide in processing the 809 request or to save it for other uses, such as within source links or 810 versioning metadata. However, an origin server &MUST-NOT; use such context 811 information to alter the request semantics. 812 </t> 813 <t> 814 For example, if a client makes a PUT request on a negotiated resource and 815 the origin server accepts that PUT (without redirection), then the new set 816 of values for that resource is expected to be consistent with the one 817 representation supplied in that PUT; the Content-Location cannot be used as 818 a form of reverse content selection identifier to update only one of the 819 negotiated representations. If the user agent had wanted the latter 820 semantics, it would have applied the PUT directly to the Content-Location 821 URI. 826 822 </t> 827 823 </section> … … 3026 3022 <x:ref>target resource</x:ref> does not have a representation of 3027 3023 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). 3024 The <x:ref>Location</x:ref> field value refers to a resource that is 3025 descriptive of the target resource, such that the follow-on representation 3026 might be useful to recipients without implying that it adequately 3027 represents the target resource. Note that answers to the questions of what 3028 can be represented, what representations are adequate, and what might be a 3029 useful description are outside the scope of HTTP. 3035 3030 </t> 3036 3031 <t> … … 3455 3450 <t> 3456 3451 The response header fields allow the server to pass additional 3457 information about the response which cannot be placed in the status-line. 3458 These header fields give information about the server and about 3459 further access to the <x:ref>target resource</x:ref>. 3452 information about the response beyond what is placed in the status-line. 3453 These header fields give information about the server, about 3454 further access to the <x:ref>target resource</x:ref>, or about related 3455 resources. 3456 </t> 3457 <t> 3458 Although each response header field has a defined meaning, in general, 3459 the precise semantics might be further refined by the semantics of the 3460 request method and/or response status code. 3460 3461 </t> 3461 3462 … … 3675 3676 <x:anchor-alias value="Location"/> 3676 3677 <t> 3677 The "Location" header field &MAY; be sent in responses to refer to3678 a specific resource in accordance with the semantics of the status3679 code.3678 The "Location" header field is used in some responses to refer to a 3679 specific resource in relation to the response. The type of relationship is 3680 defined by the combination of request method and status code semantics. 3680 3681 </t> 3681 3682 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Location"/> 3682 3683 <x:ref>Location</x:ref> = <x:ref>URI-reference</x:ref> 3683 3684 </artwork></figure> 3684 <t>3685 For <x:ref>201 (Created)</x:ref> responses, the Location is the URI of the3686 new resource which was created by the request. For <x:ref>3xx (Redirection)</x:ref>3687 responses, the location &SHOULD; indicate the server's preferred URI for3688 automatic redirection to the resource.3689 </t>3690 3685 <t> 3691 3686 The field value consists of a single URI-reference. When it has the form … … 3693 3688 the final value is computed by resolving it against the effective request 3694 3689 URI (<xref target="RFC3986" x:fmt="," x:sec="5"/>). If the original URI, as 3695 navigated to by the user agent, did contain a fragment identifier, and the 3696 final value does not, then the original URI's fragment identifier is added 3697 to the final value. 3690 navigated to by the user agent, contains a fragment identifier, and the 3691 Location value does not, then the original URI's fragment identifier is 3692 appended to the Location value. 3693 </t> 3694 <t> 3695 For <x:ref>201 (Created)</x:ref> responses, the Location value refers to 3696 the primary resource created by the request. 3697 For <x:ref>3xx (Redirection)</x:ref> responses, the Location value refers 3698 to the preferred target resource for automatically redirecting the request. 3698 3699 </t> 3699 3700 <figure> 3700 <preamble>For example, the original URI "http://www.example.org/~tim", combined with a field value given as:</preamble><!--DO NOT DARE changing the vertical spacing below, it's necessary this way for xml2rfc--> 3701 <preamble>For example, a GET request for the URI reference 3702 "http://www.example.org/~tim" might result in a 3703 <x:ref>303 (See Other)</x:ref> response containing the header field:</preamble><!--DO NOT DARE changing the vertical spacing below, it's necessary this way for xml2rfc--> 3701 3704 <artwork type="example"> 3702 3705 Location: /pub/WWW/People.html#tim 3703 3706 </artwork> 3704 <postamble>would result in a final value of "http://www.example.org/pub/WWW/People.html#tim"</postamble> 3707 <postamble>which suggests that the user agent redirect to 3708 "http://www.example.org/pub/WWW/People.html#tim"</postamble> 3705 3709 </figure> 3706 3710 <figure> 3707 <preamble>An original URI "http://www.example.org/index.html#larry", combined with a field value given as:</preamble><!--DO NOT DARE changing the vertical spacing below, it's necessary this way for xml2rfc--> 3711 <preamble>Likewise, a GET request for the URI reference 3712 "http://www.example.org/index.html#larry" might result in a 3713 <x:ref>301 (Moved Permanently)</x:ref> response containing the header 3714 field:</preamble><!--DO NOT DARE changing the vertical spacing below, it's necessary this way for xml2rfc--> 3708 3715 <artwork type="example"> 3709 3716 Location: http://www.example.net/index.html 3710 3717 </artwork> 3711 <postamble>would result in a final value of "http://www.example.net/index.html#larry", preserving the original fragment identifier.</postamble> 3718 <postamble>which suggests that the user agent redirect to 3719 "http://www.example.net/index.html#larry", preserving the original fragment 3720 identifier.</postamble> 3712 3721 </figure> 3722 <t> 3723 There are circumstances in which a fragment identifier in a Location 3724 value would not be appropriate. For example, the Location header field in a 3725 <x:ref>201 (Created)</x:ref> response is supposed to provide a URI that is 3726 specific to the created resource. 3727 </t> 3713 3728 <x:note> 3714 3729 <t> 3715 3730 &Note; Some recipients attempt to recover from Location fields 3716 3731 that are not valid URI references. This specification does not mandate or 3717 define such processing, but does allow it .3732 define such processing, but does allow it for the sake of robustness. 3718 3733 </t> 3719 3734 </x:note> 3720 <t>3721 There are circumstances in which a fragment identifier in a Location URI3722 would not be appropriate. For instance, when it appears in a <x:ref>2013723 (Created)</x:ref> response, where the Location header field specifies the3724 URI for the entire created resource.3725 </t>3726 3735 <x:note> 3727 3736 <t> 3728 3737 &Note; The <x:ref>Content-Location</x:ref> header field 3729 3738 (&header-content-location;) differs from Location in that the 3730 Content-Location identifiesthe most specific resource corresponding to the3739 Content-Location refers to the most specific resource corresponding to the 3731 3740 enclosed representation. It is therefore possible for a response to contain 3732 header fields for both Location and Content-Location.3741 both the Location and Content-Location header fields. 3733 3742 </t> 3734 3743 </x:note> … … 3980 3989 </t> 3981 3990 <t> 3982 New method definitions need to indicate whether they aresafe (<xref3991 A new method definition needs to indicate whether it is safe (<xref 3983 3992 target="safe.methods"/>), idempotent (<xref target="idempotent.methods"/>), 3984 cacheable (<xref target="cacheable.methods"/>), andwhat3993 cacheable (<xref target="cacheable.methods"/>), what 3985 3994 semantics are to be associated with the payload body if any is present 3986 in the request. If a method is cacheable, the method definition ought 3987 to describe how, and under what conditions, a cache can store a response 3988 and use it to satisfy a subsequent request. 3995 in the request, and what refinements the method makes to header field 3996 or status code semantics. 3997 If the new method is cacheable, its definition ought to describe how, and 3998 under what conditions, a cache can store a response and use it to satisfy a 3999 subsequent request. 4000 If the new method can be made conditional (<xref target="Part4"/>), the 4001 definition ought to describe how to respond when the condition is false. 4002 Likewise, if the new method might have some use for partial response 4003 semantics (<xref target="Part5"/>), it ought to document this too. 3989 4004 </t> 3990 4005 </section> … … 4078 4093 When it is necessary to express semantics for a response that are not 4079 4094 defined by current status codes, a new status code can be registered. 4080 HTTP status codes are generic; they are potentially applicable to4081 any resource, not just one particular media type, "type" of resource, or4082 application. As such, it is preferred that new status codes be4083 registered in adocument that isn't specific to a single application.4095 Status codes are generic; they are potentially applicable to any resource, 4096 not just one particular media type, kind of resource, or application of 4097 HTTP. As such, it is preferred that new status codes be registered in a 4098 document that isn't specific to a single application. 4084 4099 </t> 4085 4100 <t> 4086 4101 New status codes are required to fall under one of the categories 4087 4102 defined in <xref target="status.codes"/>. To allow existing parsers to 4088 pro perly handle them, new status codes cannot disallow a payload,4103 process the response message, new status codes cannot disallow a payload, 4089 4104 although they can mandate a zero-length payload body. 4090 4105 </t> … … 4093 4108 conditions that would cause a response containing that status code (e.g., 4094 4109 combinations of request header fields and/or method(s)) along with any 4095 dependencies on response header fields (e.g., what fields are required 4096 and what fields can modify the semantics). A response that can transfer a 4097 payload ought to specify expected cache behavior (e.g., cacheability and 4098 freshness criteria, as described in &caching;) and whether the payload has 4099 any implied association with an identified resource 4100 (<xref target="identifying.payload"/>). 4110 dependencies on response header fields (e.g., what fields are required, 4111 what fields can modify the semantics, and what header field semantics are 4112 further refined when used with the new status code). 4113 </t> 4114 <t> 4115 A response that can transfer a payload ought to specify expected cache 4116 behavior (e.g., cacheability and freshness criteria, as described in 4117 &caching;) and whether the payload has any implied association with an 4118 identified resource (<xref target="identifying.payload"/>). 4101 4119 </t> 4102 4120 </section> … … 4367 4385 (delimited by commas; see &header-fields;).</t> 4368 4386 <t>If it does not use the list syntax, document how to treat messages 4369 where the headerfield occurs multiple times (a sensible default would4370 be to ignore the headerfield, but this might not always be the right4387 where the field occurs multiple times (a sensible default would 4388 be to ignore the field, but this might not always be the right 4371 4389 choice).</t> 4372 4390 <t>Note that intermediaries and software libraries might combine 4373 multiple header field instances into a single one, despite the header4374 field not allowing this. A robust format enables recipients to discover4375 these situations (good example: "Content-Type", as the comma can only4376 a ppear inside quoted strings; bad example: "Location", as a comma can4377 occur inside a URI).</t>4391 multiple header field instances into a single one, despite the 4392 field's definition not allowing the list syntax. A robust format enables 4393 recipients to discover these situations (good example: "Content-Type", 4394 as the comma can only appear inside quoted strings; 4395 bad example: "Location", as a comma can occur inside a URI).</t> 4378 4396 </x:lt> 4379 4397 <x:lt><t>Under what conditions the header field can be used; e.g., only in 4380 responses or requests, in all messages, only on responses to a particular 4381 request method.</t></x:lt> 4398 responses or requests, in all messages, only on responses to a 4399 particular request method, etc.</t></x:lt> 4400 <x:lt><t>Whether the field semantics are further refined by the context, 4401 such as by existing request methods or status codes.</t></x:lt> 4382 4402 <x:lt><t>Whether it is appropriate to list the field-name in the 4383 <x:ref>Connection</x:ref> header field (i.e., if the header field is to4384 be hop-by-hop; see &header-connection;).</t></x:lt>4385 <x:lt><t>Under what conditions intermediaries are allowed to modify the header4386 field's value, insert or delete it.</t></x:lt>4403 <x:ref>Connection</x:ref> header field (i.e., if the header field is to 4404 be hop-by-hop; see &header-connection;).</t></x:lt> 4405 <x:lt><t>Under what conditions intermediaries are allowed to insert, 4406 delete, or modify the field's value.</t></x:lt> 4387 4407 <x:lt><t>How the header field might interact with caching (see 4388 <xref target="Part6"/>).</t></x:lt>4408 <xref target="Part6"/>).</t></x:lt> 4389 4409 <x:lt><t>Whether the header field is useful or allowable in trailers (see 4390 &chunked-encoding;).</t></x:lt>4410 &chunked-encoding;).</t></x:lt> 4391 4411 <x:lt><t>Whether the header field ought to be preserved across redirects.</t></x:lt> 4392 4412 </list> … … 4619 4639 method of determining the sensitivity of any particular piece of 4620 4640 information within the context of any given request. Therefore, 4621 applications &SHOULD;supply as much control over this information as4641 applications ought to supply as much control over this information as 4622 4642 possible to the provider of that information. Four header fields are 4623 4643 worth special mention in this context: <x:ref>Server</x:ref>, … … 4631 4651 </t> 4632 4652 <t> 4633 Proxies whichserve as a portal through a network firewall &SHOULD;4653 Proxies that serve as a portal through a network firewall &SHOULD; 4634 4654 take special precautions regarding the transfer of header information 4635 that identifies thehosts behind the firewall. In particular, they4655 that might identify hosts behind the firewall. In particular, they 4636 4656 &SHOULD; remove, or replace with sanitized versions, any <x:ref>Via</x:ref> 4637 4657 fields generated behind the firewall.
Note: See TracChangeset
for help on using the changeset viewer.