Ignore:
Timestamp:
Jul 29, 2010, 11:11:34 PM (9 years ago)
Author:
fielding@…
Message:

Addresses #109: Clarify entity / representation / variant terminology

Removed entity-header adjective and ABNF and clarified distinction
between payload and representation.

Uncapitalize the phrase effective request URI so that it doesn't
dominate the prose, and define the term "target resource" to be
used instead of the "resource identified by the effective request URI".

File:
1 edited

Legend:

Unmodified
Added
Removed

  • draft-ietf-httpbis/latest/p2-semantics.xml

    r954 r965  
    277277   agreed upon semantics of the HTTP uniform interface, the intentions defined
    278278   by each request method, and the various response messages that might be
    279    expected as a result of applying that method for the requested resource.
     279   expected as a result of applying that method to the target resource.
    280280</t>
    281281<t>
    … …  
    434434<t>
    435435   The Method token indicates the method to be performed on the resource
    436    identified by the Effective Request URI (&effective-request-uri;). The
     436   identified by the effective request URI (&effective-request-uri;). The
    437437   method is case-sensitive.
    438438</t>
    … …  
    451451<t>
    452452   The list of methods allowed by a resource can be specified in an
    453    Allow header field (<xref target="header.allow"/>). The return code of the response
     453   Allow header field (<xref target="header.allow"/>). The status code of the response
    454454   always notifies the client whether a method is currently allowed on a
    455455   resource, since the set of allowed methods can change dynamically. An
    456    origin server &SHOULD; return the status code 405 (Method Not Allowed)
     456   origin server &SHOULD; respond with the status code 405 (Method Not Allowed)
    457457   if the method is known by the origin server but not allowed for the
    458    requested resource, and 501 (Not Implemented) if the method is
     458   resource, and 501 (Not Implemented) if the method is
    459459   unrecognized or not implemented by the origin server. The methods GET
    460460   and HEAD &MUST; be supported by all general-purpose servers. All other
    … …  
    522522   experimental header fields &MAY; be given the semantics of request-header
    523523   fields if all parties in the communication recognize them to
    524    be request-header fields. Unrecognized header fields are treated as
    525    entity-header fields.
     524   be request-header fields.
    526525</t>
    527526</section>
    … …  
    635634   information about the response which cannot be placed in the Status-Line.
    636635   These header fields give information about the server and about
    637    further access to the resource identified by the Effective Request URI
     636   further access to the resource identified by the effective request URI
    638637   (&effective-request-uri;).
    639638</t>
    … …  
    655654   experimental header fields &MAY; be given the semantics of response-header
    656655   fields if all parties in the communication recognize them to
    657    be response-header fields. Unrecognized header fields are treated as
    658    entity-header fields.
     656   be response-header fields.
    659657</t>
    660658</section>
    … …  
    678676<section title="Identifying the Resource Associated with a Representation" anchor="identifying.response.associated.with.representation">
    679677<t>
    680    It is sometimes necessary to determine the identity of the resource
     678   It is sometimes necessary to determine an identifier for the resource
    681679   associated with a representation.
    682680</t>
    … …  
    687685<t>
    688686   In the common case, an HTTP response is a representation of the resource
    689    located at the Effective Request URI (see &effective-request-uri;). However,
     687   located at the effective request URI (see &effective-request-uri;). However,
    690688   this is not always the case. To determine the URI of the resource a
    691689   response is associated with, the following rules are used (with the first
    … …  
    694692<t><list style="numbers">
    695693   <t>If the response status code is 200 or 203 and the request method was GET,
    696    the response is a representation of the resource at the Effective Request URI.</t>
     694   the response payload is a representation of the resource identified by the effective request URI.</t>
    697695   <t>If the response status code is 204, 206, or 304 and the request method was GET
    698    or HEAD, the response is a partial representation of the resource at the
    699    Effective Request URI (see &caching-combining-headers;).</t>
     696   or HEAD, the response payload is a partial representation of the resource identified
     697   by the effective request URI (see &caching-combining-headers;).</t>
    700698   <t>If the response has a Content-Location header, and that URI is the same
    701    as the Effective Request URI, the response is a representation of the
    702    resource at the Effective Request URI.</t>
     699   as the effective request URI, the response payload is a representation of the
     700   resource identified by the effective request URI.</t>
    703701   <t>If the response has a Content-Location header, and that URI is not the
    704    same as the Effective Request URI, the response asserts that it is a
    705    representation of the resource at the Content-Location URI (but it might not
    706    be).</t>
     702   same as the effective request URI, then the response asserts that its
     703   payload is a representation of the resource identified by the
     704   Content-Location URI. However, such an assertion cannot be trusted unless
     705   it can be verified by other means (not defined by HTTP).</t>
    707706   <t>Otherwise, the response is a representation of an anonymous (i.e.,
    708707   unidentified) resource.</t>
    … …  
    776775   The OPTIONS method represents a request for information about the
    777776   communication options available on the request/response chain
    778    identified by the Effective Request URI. This method allows the client to
     777   identified by the effective request URI. This method allows the client to
    779778   determine the options and/or requirements associated with a resource,
    780779   or the capabilities of a server, without implying a resource action
    … …  
    835834   The GET method means retrieve whatever information (in the form of a
    836835   representation) currently corresponds to the resource identified by the
    837    Effective Request URI.
     836   effective request URI.
    838837</t>
    839838<t>   
    840    If the Effective Request URI identifies a data-producing process, it is the
     839   If the effective request URI identifies a data-producing process, it is the
    841840   produced data which shall be returned as the representation in the response and not
    842841   the source text of the process, unless that text happens to be the output of
    … …  
    903902   The POST method is used to request that the origin server accept the
    904903   representation enclosed in the request as data to be processed by the resource
    905    identified by the Effective Request URI. POST is designed
     904   identified by the effective request URI. POST is designed
    906905   to allow a uniform method to cover the following functions:
    907906  <list style="symbols">
    … …  
    924923<t>
    925924   The actual function performed by the POST method is determined by the
    926    server and is usually dependent on the Effective Request URI.
     925   server and is usually dependent on the effective request URI.
    927926</t>
    928927<t>
    … …  
    958957<t>
    959958   The PUT method requests that the enclosed representation be stored at the
    960    Effective Request URI. If the Effective Request URI refers to an already
     959   effective request URI. If the effective request URI refers to an already
    961960   existing resource, the enclosed representation &SHOULD; be considered a
    962961   modified version of the one residing on the origin server. Otherwise, if the
    963    Effective Request URI does not point to an existing resource, and that URI is
     962   effective request URI does not point to an existing resource, and that URI is
    964963   capable of being defined as a new resource by the requesting user
    965964   agent, the origin server can create the resource with that URI.
    966965</t>
    967966<t>   
    968    If a new resource is created at the Effective Request URI, the origin
     967   If a new resource is created at the effective request URI, the origin
    969968   server &MUST; inform the user agent
    970969   via the 201 (Created) response. If an existing resource is modified,
    … …  
    973972</t>
    974973<t>   
    975    If the resource identified by the Effective Request URI could not be
     974   If the resource identified by the effective request URI could not be
    976975   created or modified, an appropriate error response &SHOULD; be given
    977976   that reflects the nature of the problem.
    … …  
    983982<t>
    984983   If the request passes through a cache that has one or more stored
    985    responses for the Effective Request URI, those stored responses
     984   responses for the effective request URI, those stored responses
    986985   &SHOULD; be marked as stale if the response to the PUT request
    987986   has a success status code. Responses to the PUT method are
    … …  
    990989<t>
    991990   The fundamental difference between the POST and PUT requests is
    992    reflected in the different meaning of the Effective Request URI. The URI in a
     991   reflected in the different meaning of the effective request URI. The URI in a
    993992   POST request identifies the resource that will handle the enclosed
    994993   representation. That resource might be a data-accepting process, a gateway to
    … …  
    10151014</t>
    10161015<t>
    1017    Unless otherwise specified for a particular entity-header, the
    1018    entity-headers in the PUT request &SHOULD; be applied to the resource
    1019    created or modified by the PUT.
     1016   Header fields in a PUT request that are recognized as representation
     1017   metadata &SHOULD; be applied to the resource created or modified by
     1018   the PUT.  Unrecognized header fields &SHOULD; be ignored.
    10201019</t>
    10211020</section>
    … …  
    10261025<t>
    10271026   The DELETE method requests that the origin server delete the resource
    1028    identified by the Effective Request URI. This method &MAY; be overridden by
     1027   identified by the effective request URI. This method &MAY; be overridden by
    10291028   human intervention (or other means) on the origin server. The client cannot
    10301029   be guaranteed that the operation has been carried out, even if the
    … …  
    10421041</t>
    10431042<t>
    1044    If the request passes through a cache and the Effective Request URI
     1043   If the request passes through a cache and the effective request URI
    10451044   identifies one or more currently cached representations, those entries &SHOULD; be
    10461045   treated as stale. Responses to the DELETE method are not cacheable.
    … …  
    11681167  <iref primary="true" item="Status Codes" subitem="200 OK" x:for-anchor=""/>
    11691168<t>
    1170    The request has succeeded. The information returned with the response
     1169   The request has succeeded. The payload returned with the response
    11711170   is dependent on the method used in the request, for example:
    11721171  <list style="hanging">
    11731172    <t hangText="GET">
    1174           a representation corresponding to the requested resource is sent in
    1175           the response;
     1173          a representation of the resource corresponding to the effective
     1174          request URI is sent in the response;
    11761175    </t>
    11771176    <t hangText="HEAD">
    1178           the entity-header fields corresponding to the requested
    1179           resource are sent in the response without any message-body;
     1177          the same representation as GET, except without the message-body;
    11801178    </t>
    11811179    <t hangText="POST">
    … …  
    12431241  <iref primary="true" item="Status Codes" subitem="203 Non-Authoritative Information" x:for-anchor=""/>
    12441242<t>
    1245    The returned metadata in the entity-header is not the
     1243   The returned metadata in the header fields is not the
    12461244   definitive set as available from the origin server, but is gathered
    12471245   from a local or a third-party copy. The set presented &MAY; be a subset
    … …  
    12661264   additional content to return in the response payload body.  The
    12671265   resource metadata and representation metadata in the response message's
    1268    header fields refer to the requested resource and its current
    1269    representation, respectively, after the requested action.
     1266   header fields refer to the target resource
     1267   and its current representation, respectively, after the requested action.
    12701268   For example, if a 204 status code is received in response to a PUT
    12711269   and the response contains an ETag header field, then the value of
    12721270   that field is the current entity-tag for the representation that
    1273    was successfully PUT to the requested resource.
     1271   was successfully PUT.
    12741272</t>
    12751273<t>
    … …  
    13401338  <iref primary="true" item="Status Codes" subitem="300 Multiple Choices" x:for-anchor=""/>
    13411339<t>
    1342    The requested resource corresponds to any one of a set of
    1343    representations, each with its own specific location, and agent-driven
     1340   The target resource more than one
     1341   representation, each with its own specific location, and agent-driven
    13441342   negotiation information (&content-negotiation;) is being provided so that
    1345    the user (or user agent) can select a preferred representation and
    1346    redirect its request to that location.
     1343   the user (or user agent) can select a preferred representation by
     1344   redirecting its request to that location.
    13471345</t>
    13481346<t>
    13491347   Unless it was a HEAD request, the response &SHOULD; include a representation
    1350    containing a list of resource characteristics and location(s) from
     1348   containing a list of representation metadata and location(s) from
    13511349   which the user or user agent can choose the one most appropriate. The
    13521350   data format is specified by the media type given in the Content-Type
    … …  
    13731371  <iref primary="true" item="Status Codes" subitem="301 Moved Permanently" x:for-anchor=""/>
    13741372<t>
    1375    The requested resource has been assigned a new permanent URI and any
     1373   The target resource has been assigned a new permanent URI and any
    13761374   future references to this resource &SHOULD; use one of the returned
    13771375   URIs.  Clients with link editing capabilities ought to automatically
    1378    re-link references to the Effective Request URI to one or more of the new
     1376   re-link references to the effective request URI to one or more of the new
    13791377   references returned by the server, where possible.
    13801378</t>
    … …  
    14101408  <iref primary="true" item="Status Codes" subitem="302 Found" x:for-anchor=""/>
    14111409<t>
    1412    The requested resource resides temporarily under a different URI.
     1410   The target resource resides temporarily under a different URI.
    14131411   Since the redirection might be altered on occasion, the client &SHOULD;
    1414    continue to use the Effective Request URI for future requests.
     1412   continue to use the effective request URI for future requests.
    14151413</t>
    14161414<t>
    … …  
    14571455   representation corresponding to the response, be redirected again,
    14581456   or end with an error status.  The Location URI is not a substitute
    1459    reference for the originally requested resource.
     1457   reference for the effective request URI.
    14601458</t>
    14611459<t>
    … …  
    14711469   resource does not have a representation of its own that can be
    14721470   transferred by the server over HTTP.  The Location URI indicates a
    1473    resource that is descriptive of the requested resource such that
    1474    the follow-on representation might be useful without implying that
    1475    it adequately represents the previously requested resource.
     1471   resource that is descriptive of the target resource, such that the
     1472   follow-on representation might be useful to recipients without
     1473   implying that it adequately represents the target resource.
    14761474   Note that answers to the questions of what can be represented, what
    14771475   representations are adequate, and what might be a useful description
    … …  
    15201518  <iref primary="true" item="Status Codes" subitem="307 Temporary Redirect" x:for-anchor=""/>
    15211519<t>
    1522    The requested resource resides temporarily under a different URI.
     1520   The target resource resides temporarily under a different URI.
    15231521   Since the redirection can change over time, the client &SHOULD;
    1524    continue to use the Effective Request URI for future requests.
     1522   continue to use the effective request URI for future requests.
    15251523</t>
    15261524<t>
    … …  
    16101608  <iref primary="true" item="Status Codes" subitem="404 Not Found" x:for-anchor=""/>
    16111609<t>
    1612    The server has not found anything matching the Effective Request URI. No
     1610   The server has not found anything matching the effective request URI. No
    16131611   indication is given of whether the condition is temporary or
    16141612   permanent. The 410 (Gone) status code &SHOULD; be used if the server
    … …  
    16251623  <iref primary="true" item="Status Codes" subitem="405 Method Not Allowed" x:for-anchor=""/>
    16261624<t>
    1627    The method specified in the Request-Line is not allowed for the
    1628    resource identified by the Effective Request URI. The response &MUST; include an
     1625   The method specified in the Request-Line is not allowed for the target
     1626   resource. The response &MUST; include an
    16291627   Allow header containing a list of valid methods for the requested
    16301628   resource.
    … …  
    17141712  <iref primary="true" item="Status Codes" subitem="410 Gone" x:for-anchor=""/>
    17151713<t>
    1716    The requested resource is no longer available at the server and no
     1714   The target resource is no longer available at the server and no
    17171715   forwarding address is known. This condition is expected to be
    17181716   considered permanent. Clients with link editing capabilities &SHOULD;
    1719    delete references to the Effective Request URI after user approval. If the
     1717   delete references to the effective request URI after user approval. If the
    17201718   server does not know, or has no facility to determine, whether or not
    17211719   the condition is permanent, the status code 404 (Not Found) &SHOULD; be
    … …  
    17841782  <iref primary="true" item="Status Codes" subitem="414 URI Too Long" x:for-anchor=""/>
    17851783<t>
    1786    The server is refusing to service the request because the Effective Request URI
     1784   The server is refusing to service the request because the effective request URI
    17871785   is longer than the server is willing to interpret. This rare
    17881786   condition is only likely to occur when a client has improperly
    … …  
    17921790   itself), or when the server is under attack by a client attempting to
    17931791   exploit security holes present in some servers using fixed-length
    1794    buffers for reading or manipulating the Effective Request URI.
     1792   buffers for reading or manipulating the effective request URI.
    17951793</t>
    17961794</section>
    … …  
    18011799<t>
    18021800   The server is refusing to service the request because the representation of
    1803    the request is in a format not supported by the requested resource
     1801   the request is in a format not supported by the target resource
    18041802   for the requested method.
    18051803</t>
    … …  
    19321930   related to request and response semantics.
    19331931</t>
    1934 <t>
    1935    For entity-header fields, both sender and recipient refer to either the
    1936    client or the server, depending on who sends and who receives the message.
    1937 </t>
    19381932
    19391933<section title="Allow" anchor="header.allow">
    … …  
    19441938<t>
    19451939   The "Allow" response-header field lists the set of methods advertised as
    1946    supported by the resource identified by the Effective Request URI. The purpose of
     1940   supported by the target resource. The purpose of
    19471941   this field is strictly to inform the recipient of valid methods
    19481942   associated with the resource.
    … …  
    21772171<t>
    21782172   The "Referer" [sic] request-header field allows the client to specify the
    2179    URI of the resource from which the Effective Request URI was obtained (the
     2173   URI of the resource from which the effective request URI was obtained (the
    21802174   "referrer", although the header field is misspelled.).
    21812175</t>
    … …  
    21892183</t>
    21902184<t>
    2191    If the Effective Request URI was obtained from a source that does not have its own
     2185   If the effective request URI was obtained from a source that does not have its own
    21922186   URI (e.g., input from the user keyboard), the Referer field &MUST; either be
    21932187   sent with the value "about:blank", or not be sent at all. Note that this
    … …  
    22062200<t>
    22072201   If the field value is a relative URI, it &SHOULD; be interpreted
    2208    relative to the Effective Request URI. The URI &MUST-NOT; include a fragment. See
     2202   relative to the effective request URI. The URI &MUST-NOT; include a fragment. See
    22092203   <xref target="encoding.sensitive.information.in.uris"/> for security considerations.
    22102204</t>
    … …  
    32903284<t>
    32913285  Deprecate 305 Use Proxy status code, because user agents did not implement it.
    3292   It used to indicate that the requested resource must be accessed through the
     3286  It used to indicate that the target resource must be accessed through the
    32933287  proxy given by the Location field. The Location field gave the URI of the
    32943288  proxy. The recipient was expected to repeat this single request via the proxy.
Note: See TracChangeset for help on using the changeset viewer.