Changeset 2067


Ignore:
Timestamp:
Dec 29, 2012, 4:22:16 PM (7 years ago)
Author:
fielding@…
Message:

(editorial) clarify that header fields are refined by method and status code semantics; more rephrasing to identify subject of requirements; partly addresses #419

Location:
draft-ietf-httpbis/latest
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • draft-ietf-httpbis/latest/p2-semantics.html

    r2065 r2067  
    11121112      </p>
    11131113      <ul>
    1114          <li>For a response to a GET or HEAD request, this is an indication that the effective request URI identifies a resource that is
     1114         <li>For a response to a GET or HEAD request, this is an indication that the effective request URI refers to a resource that is
    11151115            subject to content negotiation and the Content-Location field-value is a more specific identifier for the selected representation.
    11161116         </li>
     
    11221122         </li>
    11231123      </ul>
    1124       <p id="rfc.section.3.1.4.2.p.6">If Content-Location is included in a request message, then it <em class="bcp14">MAY</em> be interpreted by the origin server as an indication of where the user agent originally obtained the content of the enclosed
    1125          representation (prior to any subsequent modification of the content by that user agent). In other words, the user agent is
    1126          providing the same representation metadata that it received with the original representation. However, such interpretation <em class="bcp14">MUST NOT</em> be used to alter the semantics of the method requested by the client. For example, if a client makes a PUT request on a negotiated
    1127          resource and the origin server accepts that PUT (without redirection), then the new set of values for that resource is expected
    1128          to be consistent with the one representation supplied in that PUT; the Content-Location cannot be used as a form of reverse
    1129          content selection that identifies only one of the negotiated representations to be updated. If the user agent had wanted the
    1130          latter semantics, it would have applied the PUT directly to the Content-Location URI.
    1131       </p>
    1132       <p id="rfc.section.3.1.4.2.p.7">A Content-Location field received in a request message is transitory information that <em class="bcp14">SHOULD NOT</em> be saved with other representation metadata for use in later responses. The Content-Location's value might be saved for use
    1133          in other contexts, such as within source links or other metadata.
    1134       </p>
    1135       <p id="rfc.section.3.1.4.2.p.8">A cache cannot assume that a representation with a Content-Location different from the URI used to retrieve it can be used
    1136          to respond to later requests on that Content-Location URI.
     1124      <p id="rfc.section.3.1.4.2.p.6">A user agent that sends Content-Location in a request message is stating that its value refers to where the user agent originally
     1125         obtained the content of the enclosed representation (prior to any modifications made by that user agent). In other words,
     1126         the user agent is providing a back link to the source of the original representation.
     1127      </p>
     1128      <p id="rfc.section.3.1.4.2.p.7">An origin server that receives a Content-Location field in a request message <em class="bcp14">MUST</em> treat the information as transitory request context rather than as metadata to be saved verbatim as part of the representation.
     1129         An origin server <em class="bcp14">MAY</em> use that context to guide in processing the request or to save it for other uses, such as within source links or versioning
     1130         metadata. However, an origin server <em class="bcp14">MUST NOT</em> use such context information to alter the request semantics.
     1131      </p>
     1132      <p id="rfc.section.3.1.4.2.p.8">For example, if a client makes a PUT request on a negotiated resource and the origin server accepts that PUT (without redirection),
     1133         then the new set of values for that resource is expected to be consistent with the one representation supplied in that PUT;
     1134         the Content-Location cannot be used as a form of reverse content selection identifier to update only one of the negotiated
     1135         representations. If the user agent had wanted the latter semantics, it would have applied the PUT directly to the Content-Location
     1136         URI.
    11371137      </p>
    11381138      <h2 id="rfc.section.3.2"><a href="#rfc.section.3.2">3.2</a>&nbsp;<a id="representation.data" href="#representation.data">Representation Data</a></h2>
     
    25642564         can be separately identified, bookmarked, and cached independent of the original request.
    25652565      </p>
    2566       <p id="rfc.section.6.4.4.p.3">A 303 response to a GET request indicates that the <a href="#resources" class="smpl">target resource</a> does not have a representation of its own that can be transferred by the server over HTTP. The <a href="#header.location" class="smpl">Location</a> URI identifies a resource that is descriptive of the target resource, such that the follow-on representation might be useful
    2567          to recipients without implying that it adequately represents the target resource. Note that answers to the questions of what
    2568          can be represented, what representations are adequate, and what might be a useful description are outside the scope of HTTP
    2569          and thus entirely determined by the URI owner(s).
     2566      <p id="rfc.section.6.4.4.p.3">A 303 response to a GET request indicates that the <a href="#resources" class="smpl">target resource</a> does not have a representation of its own that can be transferred by the server over HTTP. The <a href="#header.location" class="smpl">Location</a> field value refers to a resource that is descriptive of the target resource, such that the follow-on representation might
     2567         be useful to recipients without implying that it adequately represents the target resource. Note that answers to the questions
     2568         of what can be represented, what representations are adequate, and what might be a useful description are outside the scope
     2569         of HTTP.
    25702570      </p>
    25712571      <p id="rfc.section.6.4.4.p.4">Except for responses to a HEAD request, the representation of a 303 response ought to contain a short hypertext note with
     
    27512751      </p>
    27522752      <h1 id="rfc.section.7"><a href="#rfc.section.7">7.</a>&nbsp;<a id="response.header.fields" href="#response.header.fields">Response Header Fields</a></h1>
    2753       <p id="rfc.section.7.p.1">The response header fields allow the server to pass additional information about the response which cannot be placed in the
    2754          status-line. These header fields give information about the server and about further access to the <a href="#resources" class="smpl">target resource</a>.
     2753      <p id="rfc.section.7.p.1">The response header fields allow the server to pass additional information about the response beyond what is placed in the
     2754         status-line. These header fields give information about the server, about further access to the <a href="#resources" class="smpl">target resource</a>, or about related resources.
     2755      </p>
     2756      <p id="rfc.section.7.p.2">Although each response header field has a defined meaning, in general, the precise semantics might be further refined by the
     2757         semantics of the request method and/or response status code.
    27552758      </p>
    27562759      <h2 id="rfc.section.7.1"><a href="#rfc.section.7.1">7.1</a>&nbsp;<a id="response.control.data" href="#response.control.data">Control Data</a></h2>
     
    28952898      <div id="rfc.iref.l.1"></div>
    28962899      <h3 id="rfc.section.7.1.2"><a href="#rfc.section.7.1.2">7.1.2</a>&nbsp;<a id="header.location" href="#header.location">Location</a></h3>
    2897       <p id="rfc.section.7.1.2.p.1">The "Location" header field <em class="bcp14">MAY</em> be sent in responses to refer to a specific resource in accordance with the semantics of the status code.
     2900      <p id="rfc.section.7.1.2.p.1">The "Location" header field is used in some responses to refer to a specific resource in relation to the response. The type
     2901         of relationship is defined by the combination of request method and status code semantics.
    28982902      </p>
    28992903      <div id="rfc.figure.u.51"></div><pre class="inline"><span id="rfc.iref.g.56"></span>  <a href="#header.location" class="smpl">Location</a> = <a href="#imported.abnf" class="smpl">URI-reference</a>
    2900 </pre><p id="rfc.section.7.1.2.p.3">For <a href="#status.201" class="smpl">201 (Created)</a> responses, the Location is the URI of the new resource which was created by the request. For <a href="#status.3xx" class="smpl">3xx (Redirection)</a> responses, the location <em class="bcp14">SHOULD</em> indicate the server's preferred URI for automatic redirection to the resource.
    2901       </p>
    2902       <p id="rfc.section.7.1.2.p.4">The field value consists of a single URI-reference. When it has the form of a relative reference (<a href="#RFC3986" id="rfc.xref.RFC3986.1"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="http://tools.ietf.org/html/rfc3986#section-4.2">Section 4.2</a>), the final value is computed by resolving it against the effective request URI (<a href="#RFC3986" id="rfc.xref.RFC3986.2"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="http://tools.ietf.org/html/rfc3986#section-5">Section 5</a>). If the original URI, as navigated to by the user agent, did contain a fragment identifier, and the final value does not,
    2903          then the original URI's fragment identifier is added to the final value.
     2904</pre><p id="rfc.section.7.1.2.p.3">The field value consists of a single URI-reference. When it has the form of a relative reference (<a href="#RFC3986" id="rfc.xref.RFC3986.1"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="http://tools.ietf.org/html/rfc3986#section-4.2">Section 4.2</a>), the final value is computed by resolving it against the effective request URI (<a href="#RFC3986" id="rfc.xref.RFC3986.2"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="http://tools.ietf.org/html/rfc3986#section-5">Section 5</a>). If the original URI, as navigated to by the user agent, contains a fragment identifier, and the Location value does not,
     2905         then the original URI's fragment identifier is appended to the Location value.
     2906      </p>
     2907      <p id="rfc.section.7.1.2.p.4">For <a href="#status.201" class="smpl">201 (Created)</a> responses, the Location value refers to the primary resource created by the request. For <a href="#status.3xx" class="smpl">3xx (Redirection)</a> responses, the Location value refers to the preferred target resource for automatically redirecting the request.
    29042908      </p>
    29052909      <div id="rfc.figure.u.52"></div>
    2906       <p>For example, the original URI "http://www.example.org/~tim", combined with a field value given as:</p>  <pre class="text">  Location: /pub/WWW/People.html#tim
    2907 </pre>  <p>would result in a final value of "http://www.example.org/pub/WWW/People.html#tim"</p>
     2910      <p>For example, a GET request for the URI reference "http://www.example.org/~tim" might result in a <a href="#status.303" class="smpl">303 (See Other)</a> response containing the header field:
     2911      </p>  <pre class="text">  Location: /pub/WWW/People.html#tim
     2912</pre>  <p>which suggests that the user agent redirect to "http://www.example.org/pub/WWW/People.html#tim"</p>
    29082913      <div id="rfc.figure.u.53"></div>
    2909       <p>An original URI "http://www.example.org/index.html#larry", combined with a field value given as:</p>  <pre class="text">  Location: http://www.example.net/index.html
    2910 </pre>  <p>would result in a final value of "http://www.example.net/index.html#larry", preserving the original fragment identifier.</p>
    2911       <div class="note" id="rfc.section.7.1.2.p.7">
     2914      <p>Likewise, a GET request for the URI reference "http://www.example.org/index.html#larry" might result in a <a href="#status.301" class="smpl">301 (Moved Permanently)</a> response containing the header field:
     2915      </p>  <pre class="text">  Location: http://www.example.net/index.html
     2916</pre>  <p>which suggests that the user agent redirect to "http://www.example.net/index.html#larry", preserving the original fragment
     2917         identifier.
     2918      </p>
     2919      <p id="rfc.section.7.1.2.p.7">There are circumstances in which a fragment identifier in a Location value would not be appropriate. For example, the Location
     2920         header field in a <a href="#status.201" class="smpl">201 (Created)</a> response is supposed to provide a URI that is specific to the created resource.
     2921      </p>
     2922      <div class="note" id="rfc.section.7.1.2.p.8">
    29122923         <p> <b>Note:</b> Some recipients attempt to recover from Location fields that are not valid URI references. This specification does not mandate
    2913             or define such processing, but does allow it.
     2924            or define such processing, but does allow it for the sake of robustness.
    29142925         </p>
    29152926      </div>
    2916       <p id="rfc.section.7.1.2.p.8">There are circumstances in which a fragment identifier in a Location URI would not be appropriate. For instance, when it appears
    2917          in a <a href="#status.201" class="smpl">201
    2918             (Created)</a> response, where the Location header field specifies the URI for the entire created resource.
    2919       </p>
    29202927      <div class="note" id="rfc.section.7.1.2.p.9">
    2921          <p> <b>Note:</b> The <a href="#header.content-location" class="smpl">Content-Location</a> header field (<a href="#header.content-location" id="rfc.xref.header.content-location.3" title="Content-Location">Section&nbsp;3.1.4.2</a>) differs from Location in that the Content-Location identifies the most specific resource corresponding to the enclosed representation.
    2922             It is therefore possible for a response to contain header fields for both Location and Content-Location.
     2928         <p> <b>Note:</b> The <a href="#header.content-location" class="smpl">Content-Location</a> header field (<a href="#header.content-location" id="rfc.xref.header.content-location.3" title="Content-Location">Section&nbsp;3.1.4.2</a>) differs from Location in that the Content-Location refers to the most specific resource corresponding to the enclosed representation.
     2929            It is therefore possible for a response to contain both the Location and Content-Location header fields.
    29232930         </p>
    29242931      </div>
     
    30993106         value of "0".
    31003107      </p>
    3101       <p id="rfc.section.8.1.2.p.3">New method definitions need to indicate whether they are safe (<a href="#safe.methods" title="Safe Methods">Section&nbsp;4.2.1</a>), idempotent (<a href="#idempotent.methods" title="Idempotent Methods">Section&nbsp;4.2.2</a>), cacheable (<a href="#cacheable.methods" title="Cacheable Methods">Section&nbsp;4.2.3</a>), and what semantics are to be associated with the payload body if any is present in the request. If a method is cacheable,
    3102          the method definition ought to describe how, and under what conditions, a cache can store a response and use it to satisfy
    3103          a subsequent request.
     3108      <p id="rfc.section.8.1.2.p.3">A new method definition needs to indicate whether it is safe (<a href="#safe.methods" title="Safe Methods">Section&nbsp;4.2.1</a>), idempotent (<a href="#idempotent.methods" title="Idempotent Methods">Section&nbsp;4.2.2</a>), cacheable (<a href="#cacheable.methods" title="Cacheable Methods">Section&nbsp;4.2.3</a>), what semantics are to be associated with the payload body if any is present in the request, and what refinements the method
     3109         makes to header field or status code semantics. If the new method is cacheable, its definition ought to describe how, and
     3110         under what conditions, a cache can store a response and use it to satisfy a subsequent request. If the new method can be made
     3111         conditional (<a href="#Part4" id="rfc.xref.Part4.14"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests">[Part4]</cite></a>), the definition ought to describe how to respond when the condition is false. Likewise, if the new method might have some
     3112         use for partial response semantics (<a href="#Part5" id="rfc.xref.Part5.12"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Range Requests">[Part5]</cite></a>), it ought to document this too.
    31043113      </p>
    31053114      <h3 id="rfc.section.8.1.3"><a href="#rfc.section.8.1.3">8.1.3</a>&nbsp;<a id="method.registration" href="#method.registration">Registrations</a></h3>
     
    31863195      <h3 id="rfc.section.8.2.2"><a href="#rfc.section.8.2.2">8.2.2</a>&nbsp;<a id="considerations.for.new.status.codes" href="#considerations.for.new.status.codes">Considerations for New Status Codes</a></h3>
    31873196      <p id="rfc.section.8.2.2.p.1">When it is necessary to express semantics for a response that are not defined by current status codes, a new status code can
    3188          be registered. HTTP status codes are generic; they are potentially applicable to any resource, not just one particular media
    3189          type, "type" of resource, or application. As such, it is preferred that new status codes be registered in a document that
     3197         be registered. Status codes are generic; they are potentially applicable to any resource, not just one particular media type,
     3198         kind of resource, or application of HTTP. As such, it is preferred that new status codes be registered in a document that
    31903199         isn't specific to a single application.
    31913200      </p>
    3192       <p id="rfc.section.8.2.2.p.2">New status codes are required to fall under one of the categories defined in <a href="#status.codes" title="Response Status Codes">Section&nbsp;6</a>. To allow existing parsers to properly handle them, new status codes cannot disallow a payload, although they can mandate
    3193          a zero-length payload body.
     3201      <p id="rfc.section.8.2.2.p.2">New status codes are required to fall under one of the categories defined in <a href="#status.codes" title="Response Status Codes">Section&nbsp;6</a>. To allow existing parsers to process the response message, new status codes cannot disallow a payload, although they can
     3202         mandate a zero-length payload body.
    31943203      </p>
    31953204      <p id="rfc.section.8.2.2.p.3">A definition for a new status code ought to explain the request conditions that would cause a response containing that status
    31963205         code (e.g., combinations of request header fields and/or method(s)) along with any dependencies on response header fields
    3197          (e.g., what fields are required and what fields can modify the semantics). A response that can transfer a payload ought to
    3198          specify expected cache behavior (e.g., cacheability and freshness criteria, as described in <a href="#Part6" id="rfc.xref.Part6.15"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>) and whether the payload has any implied association with an identified resource (<a href="#identifying.payload" title="Identifying a Representation">Section&nbsp;3.1.4.1</a>).
     3206         (e.g., what fields are required, what fields can modify the semantics, and what header field semantics are further refined
     3207         when used with the new status code).
     3208      </p>
     3209      <p id="rfc.section.8.2.2.p.4">A response that can transfer a payload ought to specify expected cache behavior (e.g., cacheability and freshness criteria,
     3210         as described in <a href="#Part6" id="rfc.xref.Part6.15"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>) and whether the payload has any implied association with an identified resource (<a href="#identifying.payload" title="Identifying a Representation">Section&nbsp;3.1.4.1</a>).
    31993211      </p>
    32003212      <h3 id="rfc.section.8.2.3"><a href="#rfc.section.8.2.3">8.2.3</a>&nbsp;<a id="status.code.registration" href="#status.code.registration">Registrations</a></h3>
     
    34673479            <p>Whether the field is a single value, or whether it can be a list (delimited by commas; see <a href="p1-messaging.html#header.fields" title="Header Fields">Section 3.2</a> of <a href="#Part1" id="rfc.xref.Part1.34"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>).
    34683480            </p>
    3469             <p>If it does not use the list syntax, document how to treat messages where the header field occurs multiple times (a sensible
    3470                default would be to ignore the header field, but this might not always be the right choice).
     3481            <p>If it does not use the list syntax, document how to treat messages where the field occurs multiple times (a sensible default
     3482               would be to ignore the field, but this might not always be the right choice).
    34713483            </p>
    34723484            <p>Note that intermediaries and software libraries might combine multiple header field instances into a single one, despite the
    3473                header field not allowing this. A robust format enables recipients to discover these situations (good example: "Content-Type",
    3474                as the comma can only appear inside quoted strings; bad example: "Location", as a comma can occur inside a URI).
     3485               field's definition not allowing the list syntax. A robust format enables recipients to discover these situations (good example:
     3486               "Content-Type", as the comma can only appear inside quoted strings; bad example: "Location", as a comma can occur inside a
     3487               URI).
    34753488            </p>
    34763489         </li>
    34773490         <li>
    34783491            <p>Under what conditions the header field can be used; e.g., only in responses or requests, in all messages, only on responses
    3479                to a particular request method.
     3492               to a particular request method, etc.
    34803493            </p>
     3494         </li>
     3495         <li>
     3496            <p>Whether the field semantics are further refined by the context, such as by existing request methods or status codes.</p>
    34813497         </li>
    34823498         <li>
     
    34853501         </li>
    34863502         <li>
    3487             <p>Under what conditions intermediaries are allowed to modify the header field's value, insert or delete it.</p>
     3503            <p>Under what conditions intermediaries are allowed to insert, delete, or modify the field's value.</p>
    34883504         </li>
    34893505         <li>
     
    37223738      <p id="rfc.section.9.1.p.1">Like any generic data transfer protocol, HTTP cannot regulate the content of the data that is transferred, nor is there any
    37233739         a priori method of determining the sensitivity of any particular piece of information within the context of any given request.
    3724          Therefore, applications <em class="bcp14">SHOULD</em> supply as much control over this information as possible to the provider of that information. Four header fields are worth
    3725          special mention in this context: <a href="#header.server" class="smpl">Server</a>, <a href="p1-messaging.html#header.via" class="smpl">Via</a>, <a href="#header.referer" class="smpl">Referer</a> and <a href="#header.from" class="smpl">From</a>.
     3740         Therefore, applications ought to supply as much control over this information as possible to the provider of that information.
     3741         Four header fields are worth special mention in this context: <a href="#header.server" class="smpl">Server</a>, <a href="p1-messaging.html#header.via" class="smpl">Via</a>, <a href="#header.referer" class="smpl">Referer</a> and <a href="#header.from" class="smpl">From</a>.
    37263742      </p>
    37273743      <p id="rfc.section.9.1.p.2">Revealing the specific software version of the server might allow the server machine to become more vulnerable to attacks
    37283744         against software that is known to contain security holes. Implementers <em class="bcp14">SHOULD</em> make the <a href="#header.server" class="smpl">Server</a> header field a configurable option.
    37293745      </p>
    3730       <p id="rfc.section.9.1.p.3">Proxies which serve as a portal through a network firewall <em class="bcp14">SHOULD</em> take special precautions regarding the transfer of header information that identifies the hosts behind the firewall. In particular,
     3746      <p id="rfc.section.9.1.p.3">Proxies that serve as a portal through a network firewall <em class="bcp14">SHOULD</em> take special precautions regarding the transfer of header information that might identify hosts behind the firewall. In particular,
    37313747         they <em class="bcp14">SHOULD</em> remove, or replace with sanitized versions, any <a href="p1-messaging.html#header.via" class="smpl">Via</a> fields generated behind the firewall.
    37323748      </p>
     
    45504566                     </ul>
    45514567                  </li>
    4552                   <li><em>Part4</em>&nbsp;&nbsp;<a href="#rfc.xref.Part4.1">4.3.1</a>, <a href="#rfc.xref.Part4.2">5.2</a>, <a href="#rfc.xref.Part4.3">5.2</a>, <a href="#rfc.xref.Part4.4">5.2</a>, <a href="#rfc.xref.Part4.5">5.2</a>, <a href="#rfc.xref.Part4.6">5.2</a>, <a href="#rfc.xref.Part4.7">6.1</a>, <a href="#rfc.xref.Part4.8">6.1</a>, <a href="#rfc.xref.Part4.9">6.1</a>, <a href="#rfc.xref.Part4.10">6.3.2</a>, <a href="#rfc.xref.Part4.11">6.4</a>, <a href="#rfc.xref.Part4.12">7.2</a>, <a href="#rfc.xref.Part4.13">7.2</a>, <a href="#Part4"><b>11.1</b></a><ul>
     4568                  <li><em>Part4</em>&nbsp;&nbsp;<a href="#rfc.xref.Part4.1">4.3.1</a>, <a href="#rfc.xref.Part4.2">5.2</a>, <a href="#rfc.xref.Part4.3">5.2</a>, <a href="#rfc.xref.Part4.4">5.2</a>, <a href="#rfc.xref.Part4.5">5.2</a>, <a href="#rfc.xref.Part4.6">5.2</a>, <a href="#rfc.xref.Part4.7">6.1</a>, <a href="#rfc.xref.Part4.8">6.1</a>, <a href="#rfc.xref.Part4.9">6.1</a>, <a href="#rfc.xref.Part4.10">6.3.2</a>, <a href="#rfc.xref.Part4.11">6.4</a>, <a href="#rfc.xref.Part4.12">7.2</a>, <a href="#rfc.xref.Part4.13">7.2</a>, <a href="#rfc.xref.Part4.14">8.1.2</a>, <a href="#Part4"><b>11.1</b></a><ul>
    45534569                        <li><em>Section 2.2</em>&nbsp;&nbsp;<a href="#rfc.xref.Part4.13">7.2</a></li>
    45544570                        <li><em>Section 2.3</em>&nbsp;&nbsp;<a href="#rfc.xref.Part4.10">6.3.2</a>, <a href="#rfc.xref.Part4.12">7.2</a></li>
     
    45624578                     </ul>
    45634579                  </li>
    4564                   <li><em>Part5</em>&nbsp;&nbsp;<a href="#rfc.xref.Part5.1">3.1.1.4</a>, <a href="#rfc.xref.Part5.2">3.3</a>, <a href="#rfc.xref.Part5.3">4.3.1</a>, <a href="#rfc.xref.Part5.4">4.3.1</a>, <a href="#rfc.xref.Part5.5">4.3.4</a>, <a href="#rfc.xref.Part5.6">5.1</a>, <a href="#rfc.xref.Part5.7">5.2</a>, <a href="#rfc.xref.Part5.8">6.1</a>, <a href="#rfc.xref.Part5.9">6.1</a>, <a href="#rfc.xref.Part5.10">6.1</a>, <a href="#rfc.xref.Part5.11">7.4</a>, <a href="#Part5"><b>11.1</b></a><ul>
     4580                  <li><em>Part5</em>&nbsp;&nbsp;<a href="#rfc.xref.Part5.1">3.1.1.4</a>, <a href="#rfc.xref.Part5.2">3.3</a>, <a href="#rfc.xref.Part5.3">4.3.1</a>, <a href="#rfc.xref.Part5.4">4.3.1</a>, <a href="#rfc.xref.Part5.5">4.3.4</a>, <a href="#rfc.xref.Part5.6">5.1</a>, <a href="#rfc.xref.Part5.7">5.2</a>, <a href="#rfc.xref.Part5.8">6.1</a>, <a href="#rfc.xref.Part5.9">6.1</a>, <a href="#rfc.xref.Part5.10">6.1</a>, <a href="#rfc.xref.Part5.11">7.4</a>, <a href="#rfc.xref.Part5.12">8.1.2</a>, <a href="#Part5"><b>11.1</b></a><ul>
    45654581                        <li><em>Section 3</em>&nbsp;&nbsp;<a href="#rfc.xref.Part5.8">6.1</a></li>
    45664582                        <li><em>Section 3.1</em>&nbsp;&nbsp;<a href="#rfc.xref.Part5.9">6.1</a></li>
  • draft-ietf-httpbis/latest/p2-semantics.xml

    r2065 r2067  
    779779   <list style="symbols">
    780780    <t>For a response to a GET or HEAD request, this is an indication that the
    781        effective request URI identifies a resource that is subject to content
     781       effective request URI refers to a resource that is subject to content
    782782       negotiation and the Content-Location field-value is a more specific
    783783       identifier for the selected representation.</t>
     
    796796</t>
    797797<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.
    826822</t>
    827823</section>
     
    30263022   <x:ref>target resource</x:ref> does not have a representation of
    30273023   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.
    30353030</t>
    30363031<t>
     
    34553450<t>
    34563451   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.
    34603461</t>
    34613462
     
    36753676  <x:anchor-alias value="Location"/>
    36763677<t>
    3677    The "Location" header field &MAY; be sent in responses to refer to
    3678    a specific resource in accordance with the semantics of the status
    3679    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.
    36803681</t>
    36813682<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Location"/>
    36823683  <x:ref>Location</x:ref> = <x:ref>URI-reference</x:ref>
    36833684</artwork></figure>
    3684 <t>
    3685    For <x:ref>201 (Created)</x:ref> responses, the Location is the URI of the
    3686    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 for
    3688    automatic redirection to the resource.
    3689 </t>
    36903685<t>
    36913686   The field value consists of a single URI-reference. When it has the form
     
    36933688   the final value is computed by resolving it against the effective request
    36943689   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.
    36983699</t>
    36993700<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-->
    37013704<artwork type="example">
    37023705  Location: /pub/WWW/People.html#tim
    37033706</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>
    37053709</figure>
    37063710<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-->
    37083715<artwork type="example">
    37093716  Location: http://www.example.net/index.html
    37103717</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>
    37123721</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>
    37133728<x:note>
    37143729  <t>
    37153730    &Note; Some recipients attempt to recover from Location fields
    37163731    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.
    37183733  </t>
    37193734</x:note>
    3720 <t>
    3721    There are circumstances in which a fragment identifier in a Location URI
    3722    would not be appropriate. For instance, when it appears in a <x:ref>201
    3723    (Created)</x:ref> response, where the Location header field specifies the
    3724    URI for the entire created resource.
    3725 </t>
    37263735<x:note>
    37273736  <t>
    37283737    &Note; The <x:ref>Content-Location</x:ref> header field
    37293738    (&header-content-location;) differs from Location in that the
    3730     Content-Location identifies the most specific resource corresponding to the
     3739    Content-Location refers to the most specific resource corresponding to the
    37313740    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.
    37333742  </t>
    37343743</x:note>
     
    39803989</t>
    39813990<t>
    3982    New method definitions need to indicate whether they are safe (<xref
     3991   A new method definition needs to indicate whether it is safe (<xref
    39833992   target="safe.methods"/>), idempotent (<xref target="idempotent.methods"/>),
    3984    cacheable (<xref target="cacheable.methods"/>), and what
     3993   cacheable (<xref target="cacheable.methods"/>), what
    39853994   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.
    39894004</t>
    39904005</section>
     
    40784093   When it is necessary to express semantics for a response that are not
    40794094   defined by current status codes, a new status code can be registered.
    4080    HTTP status codes are generic; they are potentially applicable to
    4081    any resource, not just one particular media type, "type" of resource, or
    4082    application. As such, it is preferred that new status codes be
    4083    registered in a document 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.
    40844099</t>
    40854100<t>
    40864101   New status codes are required to fall under one of the categories
    40874102   defined in <xref target="status.codes"/>. To allow existing parsers to
    4088    properly handle them, new status codes cannot disallow a payload,
     4103   process the response message, new status codes cannot disallow a payload,
    40894104   although they can mandate a zero-length payload body.
    40904105</t>
     
    40934108   conditions that would cause a response containing that status code (e.g.,
    40944109   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"/>).
    41014119</t>
    41024120</section>
     
    43674385      (delimited by commas; see &header-fields;).</t>
    43684386      <t>If it does not use the list syntax, document how to treat messages
    4369       where the header field occurs multiple times (a sensible default would
    4370       be to ignore the header field, but this might not always be the right
     4387      where the field occurs multiple times (a sensible default would
     4388      be to ignore the field, but this might not always be the right
    43714389      choice).</t>
    43724390      <t>Note that intermediaries and software libraries might combine
    4373       multiple header field instances into a single one, despite the header
    4374       field not allowing this. A robust format enables recipients to discover
    4375       these situations (good example: "Content-Type", as the comma can only
    4376       appear inside quoted strings; bad example: "Location", as a comma can
    4377       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>
    43784396    </x:lt>
    43794397    <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>
    43824402    <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 to
    4384     be hop-by-hop; see &header-connection;).</t></x:lt>
    4385     <x:lt><t>Under what conditions intermediaries are allowed to modify the header
    4386     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>
    43874407    <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>
    43894409    <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>
    43914411    <x:lt><t>Whether the header field ought to be preserved across redirects.</t></x:lt>
    43924412  </list>
     
    46194639   method of determining the sensitivity of any particular piece of
    46204640   information within the context of any given request. Therefore,
    4621    applications &SHOULD; supply as much control over this information as
     4641   applications ought to supply as much control over this information as
    46224642   possible to the provider of that information. Four header fields are
    46234643   worth special mention in this context: <x:ref>Server</x:ref>,
     
    46314651</t>
    46324652<t>
    4633    Proxies which serve as a portal through a network firewall &SHOULD;
     4653   Proxies that serve as a portal through a network firewall &SHOULD;
    46344654   take special precautions regarding the transfer of header information
    4635    that identifies the hosts behind the firewall. In particular, they
     4655   that might identify hosts behind the firewall. In particular, they
    46364656   &SHOULD; remove, or replace with sanitized versions, any <x:ref>Via</x:ref>
    46374657   fields generated behind the firewall.
Note: See TracChangeset for help on using the changeset viewer.