Ignore:
Timestamp:
Jul 22, 2010, 2:06:27 AM (9 years ago)
Author:
fielding@…
Message:

Addresses #109: Clarify entity / representation / variant terminology

Replaced entity with representation.

File:
1 edited

Legend:

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

    r858 r866  
    602602   safely assume that there was something wrong with its request and
    603603   treat the response as if it had received a 400 status code. In such
    604    cases, user agents &SHOULD; present to the user the entity returned
    605    with the response, since that entity is likely to include human-readable
     604   cases, user agents &SHOULD; present to the user the representation enclosed
     605   with the response, since that representation is likely to include human-readable
    606606   information which will explain the unusual status.
    607607</t>
     
    654654</section>
    655655
    656 <section title="Entity" anchor="entity">
    657 <t>
    658    Request and Response messages &MAY; transfer an entity if not otherwise
    659    restricted by the request method or response status code. An entity
    660    consists of entity-header fields and an entity-body, although some
    661    responses will only include the entity-headers. HTTP entity-body and
    662    entity-header fields are defined in &payload;.
    663 </t>
    664 <t>
    665    An entity-body is only present in a message when a message-body is
    666    present, as described in &message-body;. The entity-body is obtained
     656<section title="Representation" anchor="entity">
     657<t>
     658   Request and Response messages &MAY; transfer a representation if not otherwise
     659   restricted by the request method or response status code. A representation
     660   consists of metadata (representation header fields) and data (representation
     661   body).  When a complete or partial representation is enclosed in an HTTP message,
     662   it is referred to as the payload of the message. HTTP representations
     663   are defined in &payload;.
     664</t>
     665<t>
     666   A representation body is only present in a message when a message-body is
     667   present, as described in &message-body;. The representation body is obtained
    667668   from the message-body by decoding any Transfer-Encoding that might
    668669   have been applied to ensure safe and proper transfer of the message.
     
    838839<t>   
    839840   If the Effective Request URI identifies a data-producing process, it is the
    840    produced data which shall be returned as the entity in the response and not
     841   produced data which shall be returned as the representation in the response and not
    841842   the source text of the process, unless that text happens to be the output of
    842843   the process.
     
    846847   request message includes an If-Modified-Since, If-Unmodified-Since,
    847848   If-Match, If-None-Match, or If-Range header field. A conditional GET
    848    method requests that the entity be transferred only under the
     849   method requests that the representation be transferred only under the
    849850   circumstances described by the conditional header field(s). The
    850851   conditional GET method is intended to reduce unnecessary network
     
    855856   The semantics of the GET method change to a "partial GET" if the
    856857   request message includes a Range header field. A partial GET requests
    857    that only part of the entity be transferred, as described in &header-range;.
     858   that only part of the representation be transferred, as described in &header-range;.
    858859   The partial GET method is intended to reduce unnecessary
    859    network usage by allowing partially-retrieved entities to be
     860   network usage by allowing partially-retrieved representations to be
    860861   completed without transferring data already held by the client.
    861862</t>
     
    880881   in the HTTP headers in response to a HEAD request &SHOULD; be identical
    881882   to the information sent in response to a GET request. This method can
    882    be used for obtaining metainformation about the entity implied by the
    883    request without transferring the entity-body itself. This method is
     883   be used for obtaining metainformation about the representation implied by the
     884   request without transferring the representation body. This method is
    884885   often used for testing hypertext links for validity, accessibility,
    885886   and recent modification.
     
    950951  <iref primary="true" item="Methods" subitem="PUT" x:for-anchor=""/>
    951952<t>
    952    The PUT method requests that the enclosed entity be stored at the
     953   The PUT method requests that the enclosed representation be stored at the
    953954   Effective Request URI. If the Effective Request URI refers to an already
    954    existing resource, the enclosed entity &SHOULD; be considered as a
     955   existing resource, the enclosed representation &SHOULD; be considered a
    955956   modified version of the one residing on the origin server. Otherwise, if the
    956957   Effective Request URI does not point to an existing resource, and that URI is
     
    966967</t>
    967968<t>   
    968    If the resource could not be created or modified with the Effective Request
    969    URI, an appropriate error response &SHOULD; be given that reflects the nature
    970    of the problem. The recipient of the entity &MUST-NOT; ignore any Content-*
     969   If the resource identified by the Effective Request URI could not be
     970   created or modified, an appropriate error response &SHOULD; be given
     971   that reflects the nature of the problem.
     972   The recipient of the representation &MUST-NOT; ignore any Content-*
    971973   headers (headers starting with the prefix "Content-") that it does
    972974   not understand or implement
     
    974976</t>
    975977<t>
    976    If the request passes through a cache and the Effective Request URI
    977    identifies one or more currently cached entities, those entries &SHOULD; be
    978    treated as stale. Responses to this method are not cacheable.
     978   If the request passes through a cache that has one or more stored
     979   responses for the Effective Request URI, those stored responses
     980   &SHOULD; be marked as stale if the response to the PUT request
     981   is a success status. Responses to the PUT method are not cacheable.
    979982</t>
    980983<t>
     
    982985   reflected in the different meaning of the Effective Request URI. The URI in a
    983986   POST request identifies the resource that will handle the enclosed
    984    entity. That resource might be a data-accepting process, a gateway to
    985    some other protocol, or a separate entity that accepts annotations.
    986    In contrast, the URI in a PUT request identifies the entity enclosed
    987    with the request -- the user agent knows what URI is intended and the
    988    server &MUST-NOT; attempt to apply the request to some other resource.
     987   representation. That resource might be a data-accepting process, a gateway to
     988   some other protocol, or a document that accepts annotations.
     989   In contrast, the URI in a PUT request identifies the resource for
     990   which enclosed representation is a new or replacement value; the
     991   user agent knows what URI is intended and the server &MUST-NOT; attempt
     992   to apply the request to some other resource.
    989993   If the server desires that the request be applied to a different URI,
    990994   it &MUST; send a 301 (Moved Permanently) response; the user agent &MAY;
     
    10281032   entity describing the status, 202 (Accepted) if the action has not
    10291033   yet been enacted, or 204 (No Content) if the action has been enacted
    1030    but the response does not include an entity.
     1034   but the response does not include a representation.
    10311035</t>
    10321036<t>
     
    10491053   entity-body of a 200 (OK) response. The final recipient is either the
    10501054   origin server or the first proxy or gateway to receive a Max-Forwards
    1051    value of zero (0) in the request (see <xref target="header.max-forwards"/>). A TRACE request
    1052    &MUST-NOT; include an entity.
     1055   value of zero (0) in the request (see <xref target="header.max-forwards"/>).
     1056   A TRACE request &MUST-NOT; include a message-body.
    10531057</t>
    10541058<t>
     
    12171221   batch-oriented process that is only run once per day) without
    12181222   requiring that the user agent's connection to the server persist
    1219    until the process is completed. The entity returned with this
     1223   until the process is completed. The representation returned with this
    12201224   response &SHOULD; include an indication of the request's current status
    12211225   and either a pointer to a status monitor or some estimate of when the
     
    12761280   user input, followed by a clearing of the form in which the input is
    12771281   given so that the user can easily initiate another input action. The
    1278    response &MUST-NOT; include an entity.
     1282   response &MUST-NOT; include a message-body.
    12791283</t>
    12801284</section>
     
    13231327</t>
    13241328<t>
    1325    Unless it was a HEAD request, the response &SHOULD; include an entity
     1329   Unless it was a HEAD request, the response &SHOULD; include a representation
    13261330   containing a list of resource characteristics and location(s) from
    13271331   which the user or user agent can choose the one most appropriate. The
    1328    entity format is specified by the media type given in the Content-Type
     1332   data format is specified by the media type given in the Content-Type
    13291333   header field. Depending upon the format and the capabilities of
    13301334   the user agent, selection of the most appropriate choice &MAY; be
     
    13531357<t>
    13541358   The new permanent URI &SHOULD; be given by the Location field in the
    1355    response. Unless the request method was HEAD, the entity of the
     1359   response. Unless the request method was HEAD, the representation of the
    13561360   response &SHOULD; contain a short hypertext note with a hyperlink to
    13571361   the new URI(s).
     
    13861390<t>
    13871391   The temporary URI &SHOULD; be given by the Location field in the
    1388    response. Unless the request method was HEAD, the entity of the
     1392   response. Unless the request method was HEAD, the representation of the
    13891393   response &SHOULD; contain a short hypertext note with a hyperlink to
    13901394   the new URI(s).
     
    14521456   A 303 response &SHOULD-NOT; be cached unless it is indicated as
    14531457   cacheable by Cache-Control or Expires header fields.  Except for
    1454    responses to a HEAD request, the entity of a 303 response &SHOULD;
     1458   responses to a HEAD request, the representation of a 303 response &SHOULD;
    14551459   contain a short hypertext note with a hyperlink to the Location URI.
    14561460</t>
     
    14991503<t>
    15001504   The temporary URI &SHOULD; be given by the Location field in the
    1501    response. Unless the request method was HEAD, the entity of the
     1505   response. Unless the request method was HEAD, the representation of the
    15021506   response &SHOULD; contain a short hypertext note with a hyperlink to
    15031507   the new URI(s) , since many pre-HTTP/1.1 user agents do not
     
    15731577   If the request method was not HEAD and the server wishes to make
    15741578   public why the request has not been fulfilled, it &SHOULD; describe the
    1575    reason for the refusal in the entity.  If the server does not wish to
     1579   reason for the refusal in the representation.  If the server does not wish to
    15761580   make this information available to the client, the status code 404
    15771581   (Not Found) can be used instead.
     
    16141618</t>
    16151619<t>
    1616    Unless it was a HEAD request, the response &SHOULD; include an entity
    1617    containing a list of available entity characteristics and location(s)
     1620   Unless it was a HEAD request, the response &SHOULD; include a representation
     1621   containing a list of available representation characteristics and location(s)
    16181622   from which the user or user agent can choose the one most
    1619    appropriate. The entity format is specified by the media type given
     1623   appropriate. The data format is specified by the media type given
    16201624   in the Content-Type header field. Depending upon the format and the
    16211625   capabilities of the user agent, selection of the most appropriate
     
    16731677<t>
    16741678   Conflicts are most likely to occur in response to a PUT request. For
    1675    example, if versioning were being used and the entity being PUT
     1679   example, if versioning were being used and the representation being PUT
    16761680   included changes to a resource which conflict with those made by an
    16771681   earlier (third-party) request, the server might use the 409 response
    16781682   to indicate that it can't complete the request. In this case, the
    1679    response entity would likely contain a list of the differences
     1683   response representation would likely contain a list of the differences
    16801684   between the two versions in a format defined by the response
    16811685   Content-Type.
     
    17681772  <iref primary="true" item="Status Codes" subitem="415 Unsupported Media Type" x:for-anchor=""/>
    17691773<t>
    1770    The server is refusing to service the request because the entity of
     1774   The server is refusing to service the request because the representation of
    17711775   the request is in a format not supported by the requested resource
    17721776   for the requested method.
     
    19021906<t>
    19031907   For entity-header fields, both sender and recipient refer to either the
    1904    client or the server, depending on who sends and who receives the entity.
     1908   client or the server, depending on who sends and who receives the message.
    19051909</t>
    19061910
     
    20942098  <t>
    20952099    <x:h>Note:</x:h> The Content-Location header field (&header-content-location;) differs
    2096     from Location in that the Content-Location identifies the original
    2097     location of the entity enclosed in the response. It is therefore
    2098     possible for a response to contain header fields for both Location
    2099     and Content-Location.
     2100    from Location in that the Content-Location identifies the most specific
     2101    resource corresponding to the enclosed representation.
     2102    It is therefore possible for a response to contain header fields for
     2103    both Location and Content-Location.
    21002104  </t>
    21012105</x:note>
     
    26952699<t>
    26962700   Some methods, like TRACE (<xref target="TRACE"/>) may expose
    2697    information sent in request headers in the response entity.
     2701   information sent in request headers in the response.
    26982702   Clients &SHOULD; be careful with sensitive information, like Cookies,
    26992703   Authorization credentials and other headers that might be used to
Note: See TracChangeset for help on using the changeset viewer.