* WGs marked with an * asterisk has had at least one new draft made available during the last 5 days

Changeset 874


Ignore:
Timestamp:
2010-07-22 22:43:26 (4 years ago)
Author:
fielding@gbiv.com
Message:

Addresses #109: Clarify entity / representation / variant terminology

Replace more entity, entities, and entity-body, as appropriate.

Addresses #183: "requested resource" in content-encoding definition

Fixed.

Clarifies #178: Content-MD5 and partial responses

New terminology makes it easier to understand what is digested.

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

Legend:

Unmodified
Added
Removed
  • draft-ietf-httpbis/latest/p1-messaging.xml

    r872 r874  
    2222  <!ENTITY CONNECT                "<xref target='Part2' x:rel='#CONNECT' xmlns:x='http://purl.org/net/xml2rfc/ext'/>"> 
    2323  <!ENTITY content.negotiation    "<xref target='Part3' x:rel='#content.negotiation' xmlns:x='http://purl.org/net/xml2rfc/ext'/>"> 
    24   <!ENTITY diff-mime              "<xref target='Part3' x:rel='#differences.between.http.entities.and.rfc.2045.entities' xmlns:x='http://purl.org/net/xml2rfc/ext'/>"> 
    25   <!ENTITY entity                 "<xref target='Part3' x:rel='#entity' xmlns:x='http://purl.org/net/xml2rfc/ext'/>"> 
     24  <!ENTITY diff-mime              "<xref target='Part3' x:rel='#differences.between.http.and.mime' xmlns:x='http://purl.org/net/xml2rfc/ext'/>"> 
     25  <!ENTITY representation         "<xref target='Part3' x:rel='#representation' xmlns:x='http://purl.org/net/xml2rfc/ext'/>"> 
    2626  <!ENTITY entity-header-fields   "<xref target='Part3' x:rel='#entity.header.fields' xmlns:x='http://purl.org/net/xml2rfc/ext'/>"> 
    2727  <!ENTITY header-cache-control   "<xref target='Part6' x:rel='#header.cache-control' xmlns:x='http://purl.org/net/xml2rfc/ext'/>"> 
  • draft-ietf-httpbis/latest/p2-semantics.xml

    r867 r874  
    654654</section> 
    655655 
    656 <section title="Representation" anchor="entity"> 
     656<section title="Representation" anchor="representation"> 
    657657<t> 
    658658   Request and Response messages &MAY; transfer a representation if not otherwise 
     
    779779</t> 
    780780<t> 
    781    If the OPTIONS request includes an entity-body (as indicated by the 
     781   If the OPTIONS request includes a message-body (as indicated by the 
    782782   presence of Content-Length or Transfer-Encoding), then the media type 
    783783   &MUST; be indicated by a Content-Type field. Although this 
     
    833833  <iref primary="true" item="Methods" subitem="GET" x:for-anchor=""/> 
    834834<t> 
    835    The GET method means retrieve whatever information (in the form of an 
    836    entity) currently corresponds to the resource identified by the 
     835   The GET method means retrieve whatever information (in the form of a 
     836   representation) currently corresponds to the resource identified by the 
    837837   Effective Request URI. 
    838838</t> 
     
    850850   circumstances described by the conditional header field(s). The 
    851851   conditional GET method is intended to reduce unnecessary network 
    852    usage by allowing cached entities to be refreshed without requiring 
     852   usage by allowing cached representations to be refreshed without requiring 
    853853   multiple requests or transferring data already held by the client. 
    854854</t> 
     
    889889   The response to a HEAD request &MAY; be cacheable in the sense that the 
    890890   information contained in the response &MAY; be used to update a 
    891    previously cached entity from that resource. If the new field values 
    892    indicate that the cached entity differs from the current entity (as 
     891   previously cached representation from that resource. If the new field values 
     892   indicate that the cached representation differs from the current representation (as 
    893893   would be indicated by a change in Content-Length, Content-MD5, ETag 
    894894   or Last-Modified), then the cache &MUST; treat the cache entry as 
     
    902902<t> 
    903903   The POST method is used to request that the origin server accept the 
    904    entity enclosed in the request as data to be processed by the resource 
     904   representation enclosed in the request as data to be processed by the resource 
    905905   identified by the Effective Request URI. POST is designed 
    906906   to allow a uniform method to cover the following functions: 
     
    930930   resource that can be identified by a URI. In this case, either 200 
    931931   (OK) or 204 (No Content) is the appropriate response status, 
    932    depending on whether or not the response includes an entity that 
     932   depending on whether or not the response includes a representation that 
    933933   describes the result. 
    934934</t> 
    935935<t> 
    936936   If a resource has been created on the origin server, the response 
    937    &SHOULD; be 201 (Created) and contain an entity which describes the 
     937   &SHOULD; be 201 (Created) and contain a representation which describes the 
    938938   status of the request and refers to the new resource, and a Location 
    939939   header (see <xref target="header.location"/>). 
     
    10301030<t> 
    10311031   A successful response &SHOULD; be 200 (OK) if the response includes an 
    1032    entity describing the status, 202 (Accepted) if the action has not 
     1032   representation describing the status, 202 (Accepted) if the action has not 
    10331033   yet been enacted, or 204 (No Content) if the action has been enacted 
    10341034   but the response does not include a representation. 
     
    10361036<t> 
    10371037   If the request passes through a cache and the Effective Request URI 
    1038    identifies one or more currently cached entities, those entries &SHOULD; be 
    1039    treated as stale. Responses to this method are not cacheable. 
     1038   identifies one or more currently cached representations, those entries &SHOULD; be 
     1039   treated as stale. Responses to the DELETE method &MUST-NOT; be cached. 
    10401040</t> 
    10411041</section> 
     
    10511051   of the request message. The final recipient of the request 
    10521052   &SHOULD; reflect the message received back to the client as the 
    1053    entity-body of a 200 (OK) response. The final recipient is either the 
     1053   message-body of a 200 (OK) response. The final recipient is either the 
    10541054   origin server or the first proxy or gateway to receive a Max-Forwards 
    10551055   value of zero (0) in the request (see <xref target="header.max-forwards"/>). 
     
    10661066</t> 
    10671067<t> 
    1068    If the request is valid, the response &SHOULD; contain the entire 
    1069    request message in the entity-body, with a Content-Type of 
    1070    "message/http" (see &media-type-message-http;). Responses to this method 
    1071    &MUST-NOT; be cached. 
     1068   If the request is valid, the response &SHOULD; have a Content-Type of 
     1069   "message/http" (see &media-type-message-http;) and contain a message-body 
     1070   that encloses a copy of the entire request message. 
     1071   Responses to the TRACE method &MUST-NOT; be cached. 
    10721072</t> 
    10731073</section> 
     
    11651165  <list style="hanging"> 
    11661166    <t hangText="GET"> 
    1167           an entity corresponding to the requested resource is sent in 
     1167          a representation corresponding to the requested resource is sent in 
    11681168          the response; 
    11691169    </t> 
     
    11731173    </t> 
    11741174    <t hangText="POST"> 
    1175       an entity describing or containing the result of the action; 
     1175      a representation describing or containing the result of the action; 
    11761176    </t> 
    11771177    <t hangText="TRACE"> 
    1178       an entity containing the request message as received by the 
     1178      a representation containing the request message as received by the 
    11791179      end server. 
    11801180    </t> 
     
    12011201<t> 
    12021202   A 201 response &MAY; contain an ETag response header field indicating 
    1203    the current value of the entity tag for the representation of the resource 
     1203   the current value of the entity-tag for the representation of the resource 
    12041204   just created (see &header-etag;). 
    12051205</t> 
     
    12921292<t> 
    12931293   The server has fulfilled the partial GET request for the resource 
    1294    and the enclosed entity is a partial representation as defined in &status-206;. 
     1294   and the enclosed payload is a partial representation as defined in &status-206;. 
    12951295</t> 
    12961296</section> 
     
    15251525   The 4xx class of status code is intended for cases in which the 
    15261526   client seems to have erred. Except when responding to a HEAD request, 
    1527    the server &SHOULD; include an entity containing an explanation of the 
     1527   the server &SHOULD; include a representation containing an explanation of the 
    15281528   error situation, and whether it is a temporary or permanent 
    15291529   condition. These status codes are applicable to any request method. 
    1530    User agents &SHOULD; display any included entity to the user. 
     1530   User agents &SHOULD; display any included representation to the user. 
    15311531</t> 
    15321532<t> 
     
    16141614<t> 
    16151615   The resource identified by the request is only capable of generating 
    1616    response entities which have content characteristics not acceptable 
     1616   response representations which have content characteristics not acceptable 
    16171617   according to the accept headers sent in the request. 
    16181618</t> 
     
    16711671   and resubmit the request. The response body &SHOULD; include enough 
    16721672   information for the user to recognize the source of the conflict. 
    1673    Ideally, the response entity would include enough information for the 
     1673   Ideally, the response representation would include enough information for the 
    16741674   user or user agent to fix the problem; however, that might not be 
    16751675   possible and is not required. 
     
    17411741<t> 
    17421742   The server is refusing to process a request because the request 
    1743    entity is larger than the server is willing or able to process. The 
     1743   representation is larger than the server is willing or able to process. The 
    17441744   server &MAY; close the connection to prevent the client from continuing 
    17451745   the request. 
     
    18081808   which the server is aware that it has erred or is incapable of 
    18091809   performing the request. Except when responding to a HEAD request, the 
    1810    server &SHOULD; include an entity containing an explanation of the 
     1810   server &SHOULD; include a representation containing an explanation of the 
    18111811   error situation, and whether it is a temporary or permanent 
    1812    condition. User agents &SHOULD; display any included entity to the 
     1812   condition. User agents &SHOULD; display any included representation to the 
    18131813   user. These response codes are applicable to any request method. 
    18141814</t> 
     
    18901890   using the same major version as the client, as described in &http-version;, 
    18911891   other than with this error message. The response &SHOULD; contain 
    1892    an entity describing why that version is not supported and what other 
     1892   a representation describing why that version is not supported and what other 
    18931893   protocols are supported by that server. 
    18941894</t> 
  • draft-ietf-httpbis/latest/p3-payload.xml

    r867 r874  
    602602<section title="Canonicalization and Text Defaults" anchor="canonicalization.and.text.defaults"> 
    603603<t> 
    604    Internet media types are registered with a canonical form. An 
    605    entity-body transferred via HTTP messages &MUST; be represented in the 
     604   Internet media types are registered with a canonical form. A 
     605   representation transferred via HTTP messages &MUST; be in the 
    606606   appropriate canonical form prior to its transmission except for 
    607607   "text" types, as defined in the next paragraph. 
     
    611611   the text line break. HTTP relaxes this requirement and allows the 
    612612   transport of text media with plain CR or LF alone representing a line 
    613    break when it is done consistently for an entire entity-body. HTTP 
    614    applications &MUST; accept CRLF, bare CR, and bare LF as being 
    615    representative of a line break in text media received via HTTP. In 
    616    addition, if the text is represented in a character set that does not 
     613   break when it is done consistently for an entire representation. HTTP 
     614   applications &MUST; accept CRLF, bare CR, and bare LF as indicating 
     615   a line break in text media received via HTTP. In 
     616   addition, if the text is in a character encoding that does not 
    617617   use octets 13 and 10 for CR and LF respectively, as is the case for 
    618    some multi-byte character sets, HTTP allows the use of whatever octet 
    619    sequences are defined by that character set to represent the 
     618   some multi-byte character encodings, HTTP allows the use of whatever octet 
     619   sequences are defined by that character encoding to represent the 
    620620   equivalent of CR and LF for line breaks. This flexibility regarding 
    621    line breaks applies only to text media in the entity-body; a bare CR 
     621   line breaks applies only to text media in the payload body; a bare CR 
    622622   or LF &MUST-NOT; be substituted for CRLF within any of the HTTP control 
    623623   structures (such as header fields and multipart boundaries). 
    624624</t> 
    625625<t> 
    626    If an entity-body is encoded with a content-coding, the underlying 
     626   If a representation is encoded with a content-coding, the underlying 
    627627   data &MUST; be in a form defined above prior to being encoded. 
    628628</t> 
    629629<t> 
    630630   The "charset" parameter is used with some media types to define the 
    631    character set (<xref target="character.sets"/>) of the data. When no explicit charset 
     631   character encoding (<xref target="character.sets"/>) of the data. When no explicit charset 
    632632   parameter is provided by the sender, media subtypes of the "text" 
    633633   type are defined to have a default charset value of "ISO-8859-1" when 
    634    received via HTTP. Data in character sets other than "ISO-8859-1" or 
     634   received via HTTP. Data in character encodings other than "ISO-8859-1" or 
    635635   its subsets &MUST; be labeled with an appropriate charset value. See 
    636636   <xref target="missing.charset"/> for compatibility problems. 
     
    641641<t> 
    642642   MIME provides for a number of "multipart" types -- encapsulations of 
    643    one or more entities within a single message-body. All multipart 
     643   one or more representations within a single message-body. All multipart 
    644644   types share a common syntax, as defined in <xref target="RFC2046" x:sec="5.1.1" x:fmt="of"/>, 
    645645   and &MUST; include a boundary parameter as part of the media type 
     
    705705</section> 
    706706 
    707 <section title="Entity" anchor="entity"> 
     707<section title="Representation" anchor="representation"> 
    708708<t> 
    709709   Request and Response messages &MAY; transfer a representation if not otherwise 
     
    721721  <x:anchor-alias value="extension-header"/> 
    722722<t> 
    723    Entity-header fields define metadata about the entity-body or, 
    724    if no body is present, about the resource identified by the request. 
     723   Entity-header fields define metadata about the representation data 
     724   enclosed in the message-body or, if no message-body is present, about 
     725   the representation that would have been transferred in a 200 response 
     726   to a simultaneous GET request on the Effective Request URI. 
    725727</t> 
    726728<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="entity-header"/><iref primary="true" item="Grammar" subitem="extension-header"/> 
     
    747749</section> 
    748750 
    749 <section title="Entity Body" anchor="entity.body"> 
    750   <x:anchor-alias value="entity-body"/> 
    751 <t> 
    752    The entity-body (if any) sent with an HTTP request or response is in 
     751<section title="Payload Body" anchor="payload.body"> 
     752  <x:anchor-alias value="payload-body"/> 
     753<t> 
     754   The payload body (if any) sent with an HTTP request or response is in 
    753755   a format and encoding defined by the entity-header fields. 
    754756</t> 
    755 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="entity-body"/> 
    756   <x:ref>entity-body</x:ref>    = *<x:ref>OCTET</x:ref> 
    757 </artwork></figure> 
    758 <t> 
    759    An entity-body is only present in a message when a message-body is 
    760    present, as described in &message-body;. The entity-body is obtained 
     757<t> 
     758   A payload body is only present in a message when a message-body is 
     759   present, as described in &message-body;. The payload body is obtained 
    761760   from the message-body by decoding any Transfer-Encoding that might 
    762761   have been applied to ensure safe and proper transfer of the message. 
     
    765764<section title="Type" anchor="type"> 
    766765<t> 
    767    When an entity-body is included with a message, the data type of that 
     766   When a payload body is included with a message, the data type of that 
    768767   body is determined via the header fields Content-Type and Content-Encoding. 
    769768   These define a two-layer, ordered encoding model: 
    770769</t> 
    771770<figure><artwork type="example"> 
    772   entity-body := Content-Encoding( Content-Type( data ) ) 
     771  payload-body := Content-Encoding( Content-Type( data ) ) 
    773772</artwork></figure> 
    774773<t> 
    775774   Content-Type specifies the media type of the underlying data. Any HTTP/1.1 
    776    message containing an entity-body &SHOULD; include a Content-Type header 
     775   message containing a payload body &SHOULD; include a Content-Type header 
    777776   field defining the media type of that body, unless that information is 
    778777   unknown. 
     
    791790</t> 
    792791<t> 
    793    Client that do so risk drawing incorrect conclusions, which may expose 
     792   Clients that do so risk drawing incorrect conclusions, which may expose 
    794793   additional security risks (e.g., "privilege escalation"). Implementers are 
    795794   encouraged to provide a means of disabling such "content sniffing" when it 
     
    799798   Content-Encoding may be used to indicate any additional content 
    800799   codings applied to the data, usually for the purpose of data 
    801    compression, that are a property of the requested resource.  There is 
     800   compression, that are a property of the representation.  There is 
    802801   no default encoding. 
    803802</t> 
     
    928927   initial response from the origin server. Selection is based on a list 
    929928   of the available representations of the response included within the 
    930    header fields or entity-body of the initial response, with each 
     929   header fields or body of the initial response, with each 
    931930   representation identified by its own URI. Selection from among the 
    932931   representations may be performed automatically (if the user agent is 
     
    13421341</t> 
    13431342<t> 
    1344    If the content-coding of an entity in a request message is not 
     1343   If the content-coding of a representation in a request message is not 
    13451344   acceptable to the origin server, the server &SHOULD; respond with a 
    13461345   status code of 415 (Unsupported Media Type). 
     
    13621361   The "Content-Language" entity-header field describes the natural 
    13631362   language(s) of the intended audience for the representation. Note that this might 
    1364    not be equivalent to all the languages used within the entity-body. 
     1363   not be equivalent to all the languages used within the representation. 
    13651364</t> 
    13661365<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Content-Language"/><iref primary="true" item="Grammar" subitem="Content-Language-v"/> 
     
    15041503<t> 
    15051504   The "Content-MD5" entity-header field, as defined in <xref target="RFC1864"/>, is 
    1506    an MD5 digest of the entity-body that provides an end-to-end message 
    1507    integrity check (MIC) of the entity-body. Note that a MIC is good for 
    1508    detecting accidental modification of the entity-body in transit, but is not 
     1505   an MD5 digest of the payload body that provides an end-to-end message 
     1506   integrity check (MIC) of the payload body (the message-body after any 
     1507   transfer-coding is decoded). Note that a MIC is good for 
     1508   detecting accidental modification of the payload body in transit, but is not 
    15091509   proof against malicious attacks. 
    15101510</t> 
     
    15151515<t> 
    15161516   The Content-MD5 header field &MAY; be generated by an origin server or 
    1517    client to function as an integrity check of the entity-body. Only 
    1518    origin servers or clients &MAY; generate the Content-MD5 header field; 
     1517   client to function as an integrity check of the payload body. Only 
     1518   origin servers or user agents &MAY; generate the Content-MD5 header field; 
    15191519   proxies and gateways &MUST-NOT; generate it, as this would defeat its 
    1520    value as an end-to-end integrity check. Any recipient of the entity-body, 
    1521    including gateways and proxies, &MAY; check that the digest value 
    1522    in this header field matches that of the entity-body as received. 
    1523 </t> 
    1524 <t> 
    1525    The MD5 digest is computed based on the content of the entity-body, 
    1526    including any content-coding that has been applied, but not including 
    1527    any transfer-encoding applied to the message-body. If the message is 
    1528    received with a transfer-encoding, that encoding &MUST; be removed 
    1529    prior to checking the Content-MD5 value against the received representation. 
    1530 </t> 
    1531 <t> 
    1532    This has the result that the digest is computed on the octets of the 
    1533    entity-body exactly as, and in the order that, they would be sent if 
    1534    no transfer-encoding were being applied. 
     1520   value as an end-to-end integrity check. Any recipient &MAY; check that 
     1521   the digest value in this header field matches a corresponding digest 
     1522   calculated on payload body as received. 
     1523</t> 
     1524<t> 
     1525   The MD5 digest is computed based on the content of the payload body, 
     1526   including any content-coding, but not including any transfer-coding 
     1527   applied to the message-body because such transfer-codings might be 
     1528   applied or removed anywhere along the request/response chain. 
     1529   If the message is received with a transfer-coding, that encoding &MUST; 
     1530   be decoded prior to checking the Content-MD5 value against the received 
     1531   payload. 
    15351532</t> 
    15361533<t> 
     
    15411538</t> 
    15421539<t> 
    1543    There are several consequences of this. The entity-body for composite 
     1540   There are several consequences of this. The payload for composite 
    15441541   types &MAY; contain many body-parts, each with its own MIME and HTTP 
    15451542   headers (including Content-MD5, Content-Transfer-Encoding, and 
     
    15811578<t> 
    15821579   The "Content-Type" entity-header field indicates the media type of the 
    1583    entity-body. In the case of responses to the HEAD method, the media type is 
     1580   representation. In the case of responses to the HEAD method, the media type is 
    15841581   that which would have been sent had the request been a GET. 
    15851582</t> 
     
    15951592</artwork></figure> 
    15961593<t> 
    1597    Further discussion of methods for identifying the media type of an 
    1598    entity is provided in <xref target="type"/>. 
     1594   Further discussion of methods for identifying the media type of a 
     1595   representation is provided in <xref target="type"/>. 
    15991596</t> 
    16001597</section> 
     
    25342531</references> 
    25352532 
    2536 <section title="Differences Between HTTP Entities and RFC 2045 Entities" anchor="differences.between.http.entities.and.rfc.2045.entities"> 
     2533<section title="Differences between HTTP and MIME" anchor="differences.between.http.and.mime"> 
    25372534<t> 
    25382535   HTTP/1.1 uses many of the constructs defined for Internet Mail (<xref target="RFC5322"/>) and the Multipurpose Internet Mail Extensions (MIME <xref target="RFC2045"/>) to 
    2539    allow entities to be transmitted in an open variety of 
     2536   allow a message-body to be transmitted in an open variety of 
    25402537   representations and with extensible mechanisms. However, RFC 2045 
    25412538   discusses mail, and HTTP has a few features that are different from 
    2542    those described in RFC 2045. These differences were carefully chosen 
     2539   those described in MIME. These differences were carefully chosen 
    25432540   to optimize performance over binary connections, to allow greater 
    25442541   freedom in the use of new media types, to make date comparisons 
     
    25472544</t> 
    25482545<t> 
    2549    This appendix describes specific areas where HTTP differs from RFC 
    2550    2045. Proxies and gateways to strict MIME environments &SHOULD; be 
     2546   This appendix describes specific areas where HTTP differs from MIME. 
     2547   Proxies and gateways to strict MIME environments &SHOULD; be 
    25512548   aware of these differences and provide the appropriate conversions 
    25522549   where necessary. Proxies and gateways from MIME environments to HTTP 
     
    25822579<section title="Conversion to Canonical Form" anchor="conversion.to.canonical.form"> 
    25832580<t> 
    2584    <xref target="RFC2045"/> requires that an Internet mail entity be converted to 
     2581   MIME requires that an Internet mail body-part be converted to 
    25852582   canonical form prior to being transferred, as described in <xref target="RFC2049" x:fmt="of" x:sec="4"/>. 
    25862583   <xref target="canonicalization.and.text.defaults"/> of this document describes the forms 
     
    26232620<section title="Introduction of Content-Encoding" anchor="introduction.of.content-encoding"> 
    26242621<t> 
    2625    RFC 2045 does not include any concept equivalent to HTTP/1.1's 
     2622   MIME does not include any concept equivalent to HTTP/1.1's 
    26262623   Content-Encoding header field. Since this acts as a modifier on the 
    26272624   media type, proxies and gateways from HTTP to MIME-compliant 
    26282625   protocols &MUST; either change the value of the Content-Type header 
    2629    field or decode the entity-body before forwarding the message. (Some 
     2626   field or decode the representation before forwarding the message. (Some 
    26302627   experimental applications of Content-Type for Internet mail have used 
    26312628   a media-type parameter of ";conversions=&lt;content-coding&gt;" to perform 
    26322629   a function equivalent to Content-Encoding. However, this parameter is 
    2633    not part of RFC 2045). 
     2630   not part of the MIME standards). 
    26342631</t> 
    26352632</section> 
     
    26372634<section title="No Content-Transfer-Encoding" anchor="no.content-transfer-encoding"> 
    26382635<t> 
    2639    HTTP does not use the Content-Transfer-Encoding field of RFC 
    2640    2045. Proxies and gateways from MIME-compliant protocols to HTTP &MUST; 
     2636   HTTP does not use the Content-Transfer-Encoding field of MIME. 
     2637   Proxies and gateways from MIME-compliant protocols to HTTP &MUST; 
    26412638   remove any Content-Transfer-Encoding 
    26422639   prior to delivering the response message to an HTTP client. 
     
    28462843<x:ref>disposition-type</x:ref> = "attachment" / disp-extension-token 
    28472844 
    2848 <x:ref>entity-body</x:ref> = *OCTET 
    28492845<x:ref>entity-header</x:ref> = Content-Encoding / Content-Language / Content-Length 
    28502846 / Content-Location / Content-MD5 / Content-Range / Content-Type / 
     
    28862882; MIME-Version defined but not used 
    28872883; content-disposition defined but not used 
    2888 ; entity-body defined but not used 
    28892884; entity-header defined but not used 
    28902885</artwork></figure></section> 
  • draft-ietf-httpbis/latest/p4-conditional.xml

    r867 r874  
    307307</section> 
    308308 
    309 <section title="Entity Tags" anchor="entity.tags"> 
     309<section title="Entity-Tags" anchor="entity.tags"> 
    310310  <x:anchor-alias value="entity-tag"/> 
    311311  <x:anchor-alias value="opaque-tag"/> 
    312312  <x:anchor-alias value="weak"/> 
    313313<t> 
    314    Entity tags are used for comparing two or more entities from the same 
    315    requested resource. HTTP/1.1 uses entity tags in the ETag (<xref target="header.etag"/>), 
     314   Entity-tags are used for comparing two or more representations from the same 
     315   requested resource. HTTP/1.1 uses entity-tags in the ETag (<xref target="header.etag"/>), 
    316316   If-Match (<xref target="header.if-match"/>), If-None-Match (<xref target="header.if-none-match"/>), and 
    317317   If-Range (&header-if-range;) header fields. The definition of how they 
    318318   are used and compared as cache validators is in <xref target="weak.and.strong.validators"/>. An 
    319    entity tag consists of an opaque quoted string, possibly prefixed by 
     319   entity-tag consists of an opaque quoted string, possibly prefixed by 
    320320   a weakness indicator. 
    321321</t> 
     
    326326</artwork></figure> 
    327327<t> 
    328    A "strong entity tag" &MAY; be shared by two entities of a resource 
     328   A "strong entity-tag" &MAY; be shared by two representations of a resource 
    329329   only if they are equivalent by octet equality. 
    330330</t> 
    331331<t> 
    332    A "weak entity tag," indicated by the "W/" prefix, &MAY; be shared by 
    333    two entities of a resource only if the entities are equivalent and 
     332   A "weak entity-tag," indicated by the "W/" prefix, &MAY; be shared by 
     333   two representations of a resource only if the representations are equivalent and 
    334334   could be substituted for each other with no significant change in 
    335    semantics. A weak entity tag can only be used for weak comparison. 
    336 </t> 
    337 <t> 
    338    An entity tag &MUST; be unique across all versions of all entities 
    339    associated with a particular resource. A given entity tag value &MAY; 
    340    be used for entities obtained by requests on different URIs. The use 
    341    of the same entity tag value in conjunction with entities obtained by 
     335   semantics. A weak entity-tag can only be used for weak comparison. 
     336</t> 
     337<t> 
     338   An entity-tag &MUST; be unique across all versions of all representations 
     339   associated with a particular resource. A given entity-tag value &MAY; 
     340   be used for representations obtained by requests on different URIs. The use 
     341   of the same entity-tag value in conjunction with representations obtained by 
    342342   requests on different URIs does not imply the equivalence of those 
    343    entities. 
    344 </t> 
    345  
    346 <section title="Example: Entity Tags varying on Content-Negotiated Resources" anchor="example.entity.tag.vs.conneg"> 
     343   representations. 
     344</t> 
     345 
     346<section title="Example: Entity-tags varying on Content-Negotiated Resources" anchor="example.entity.tag.vs.conneg"> 
    347347<t> 
    348348   Consider a resource that is subject to content negotiation (&content-negotiation;), 
     
    390390  <t> 
    391391    <x:h>Note:</x:h> Content codings are a property of the representation, 
    392     so therefore an entity tag of an encoded representation must be distinct 
     392    so therefore an entity-tag of an encoded representation must be distinct 
    393393    from an unencoded representation to prevent conflicts during cache updates 
    394394    and range requests.  In contrast, transfer codings (&transfer-codings;) 
    395     apply only during message transfer and do not require distinct entity tags. 
     395    apply only during message transfer and do not require distinct entity-tags. 
    396396  </t> 
    397397</x:note> 
     
    469469</t> 
    470470<t> 
    471    Entity tags are normally "strong validators," but the protocol 
    472    provides a mechanism to tag an entity tag as "weak." One can think of 
     471   An entity-tag is normally a strong validator, but the protocol 
     472   provides a mechanism to tag an entity-tag as "weak." One can think of 
    473473   a strong validator as one that changes whenever the sequence of bits 
    474474   in a representation changes, while a weak value changes whenever the 
     
    481481      incremented in stable storage every time a representation is changed. 
    482482    </t><t> 
    483       An entity's modification time, if defined with only one-second 
     483      A representation's modification time, if defined with only one-second 
    484484      resolution, could be a weak validator, since it is possible that 
    485485      the representation might be modified twice during a single second. 
     
    524524</t> 
    525525<t> 
    526    The example below shows the results for a set of entity tag pairs, 
     526   The example below shows the results for a set of entity-tag pairs, 
    527527   and both the weak and strong comparison function results: 
    528528</t> 
     
    554554</texttable> 
    555555<t> 
    556    An entity tag is strong unless it is explicitly tagged as weak. 
    557    <xref target="entity.tags"/> gives the syntax for entity tags. 
     556   An entity-tag is strong unless it is explicitly tagged as weak. 
     557   <xref target="entity.tags"/> gives the syntax for entity-tags. 
    558558</t> 
    559559<t> 
     
    621621</section> 
    622622 
    623 <section title="Rules for When to Use Entity Tags and Last-Modified Dates" anchor="rules.for.when.to.use.entity.tags.and.last-modified.dates"> 
     623<section title="Rules for When to Use Entity-tags and Last-Modified Dates" anchor="rules.for.when.to.use.entity.tags.and.last-modified.dates"> 
    624624<t> 
    625625   We adopt a set of rules and recommendations for origin servers, 
     
    630630   HTTP/1.1 origin servers: 
    631631  <list style="symbols"> 
    632      <t>&SHOULD; send an entity tag validator unless it is not feasible to 
     632     <t>&SHOULD; send an entity-tag validator unless it is not feasible to 
    633633        generate one.</t> 
    634634 
    635      <t>&MAY; send a weak entity tag instead of a strong entity tag, if 
    636         performance considerations support the use of weak entity tags, 
    637         or if it is unfeasible to send a strong entity tag.</t> 
     635     <t>&MAY; send a weak entity-tag instead of a strong entity-tag, if 
     636        performance considerations support the use of weak entity-tags, 
     637        or if it is unfeasible to send a strong entity-tag.</t> 
    638638 
    639639     <t>&SHOULD; send a Last-Modified value if it is feasible to send one, 
     
    645645<t> 
    646646   In other words, the preferred behavior for an HTTP/1.1 origin server 
    647    is to send both a strong entity tag and a Last-Modified value. 
    648 </t> 
    649 <t> 
    650    In order to be legal, a strong entity tag &MUST; change whenever the 
    651    associated entity changes in any way. A weak entity tag &SHOULD; 
    652    change whenever the associated entity changes in a semantically 
     647   is to send both a strong entity-tag and a Last-Modified value. 
     648</t> 
     649<t> 
     650   In order to be legal, a strong entity-tag &MUST; change whenever the 
     651   associated representation changes in any way. A weak entity-tag &SHOULD; 
     652   change whenever the associated representation changes in a semantically 
    653653   significant way. 
    654654</t> 
     
    656656  <t> 
    657657    <x:h>Note:</x:h> In order to provide semantically transparent caching, an 
    658     origin server must avoid reusing a specific strong entity tag 
    659     value for two different entities, or reusing a specific weak 
    660     entity tag value for two semantically different entities. Cache 
     658    origin server must avoid reusing a specific strong entity-tag 
     659    value for two different representations, or reusing a specific weak 
     660    entity-tag value for two semantically different representations. Cache 
    661661    entries might persist for arbitrarily long periods, regardless of 
    662662    expiration times, so it might be inappropriate to expect that a 
     
    668668   HTTP/1.1 clients: 
    669669  <list style="symbols"> 
    670      <t>&MUST; use that entity tag in any cache-conditional request (using 
    671         If-Match or If-None-Match) if an entity tag has been provided by the 
     670     <t>&MUST; use that entity-tag in any cache-conditional request (using 
     671        If-Match or If-None-Match) if an entity-tag has been provided by the 
    672672        origin server.</t> 
    673673 
     
    682682 
    683683     <t>&SHOULD; use both validators in cache-conditional requests if both an 
    684         entity tag and a Last-Modified value have been provided by the origin 
     684        entity-tag and a Last-Modified value have been provided by the origin 
    685685        server. This allows both HTTP/1.0 and HTTP/1.1 caches to respond 
    686686        appropriately.</t> 
     
    690690   An HTTP/1.1 origin server, upon receiving a conditional request that 
    691691   includes both a Last-Modified date (e.g., in an If-Modified-Since or 
    692    If-Unmodified-Since header field) and one or more entity tags (e.g., 
     692   If-Unmodified-Since header field) and one or more entity-tags (e.g., 
    693693   in an If-Match, If-None-Match, or If-Range header field) as cache 
    694694   validators, &MUST-NOT; return a response status of 304 (Not Modified) 
     
    698698<t> 
    699699   An HTTP/1.1 caching proxy, upon receiving a conditional request that 
    700    includes both a Last-Modified date and one or more entity tags as 
     700   includes both a Last-Modified date and one or more entity-tags as 
    701701   cache validators, &MUST-NOT; return a locally cached response to the 
    702702   client unless that cached response is consistent with all of the 
     
    709709      conservative assumptions about the validators they receive. 
    710710  </t><t> 
    711       HTTP/1.0 clients and caches will ignore entity tags. Generally, 
     711      HTTP/1.0 clients and caches will ignore entity-tags. Generally, 
    712712      last-modified values received or used by these systems will 
    713713      support transparent and efficient caching, and so HTTP/1.1 origin 
     
    737737<t> 
    738738   The "ETag" response-header field provides the current value of the 
    739    entity tag (see <xref target="entity.tags"/>) for one representation of 
    740    the resource identified by the Effective Request URI.  An entity tag 
     739   entity-tag (see <xref target="entity.tags"/>) for one representation of 
     740   the resource identified by the Effective Request URI.  An entity-tag 
    741741   is intended for use as a resource-local identifier for differentiating 
    742742   between representations of the same resource that vary over time or via 
     
    756756</artwork></figure> 
    757757<t> 
    758    An entity tag provides an "opaque" cache validator that allows for 
     758   An entity-tag provides an "opaque" cache validator that allows for 
    759759   more reliable validation than modification dates in situations where 
    760760   it is inconvenient to store modification dates, 
     
    764764</t> 
    765765<t> 
    766    The principle behind entity tags is that only the service author 
     766   The principle behind entity-tags is that only the service author 
    767767   knows the semantics of a resource well enough to select an 
    768768   appropriate cache validation mechanism, and the specification of any 
     
    781781<t> 
    782782   The "If-Match" request-header field is used to make a request method 
    783    conditional. A client that has one or more entities previously 
    784    obtained from the resource can verify that one of those entities is 
    785    current by including a list of their associated entity tags in the 
     783   conditional. A client that has one or more representations previously 
     784   obtained from the resource can verify that one of those representations is 
     785   current by including a list of their associated entity-tags in the 
    786786   If-Match header field. 
    787787</t> 
     
    790790   transaction overhead. It is also used when updating resources, to prevent 
    791791   inadvertent modification of the wrong version of a resource. As a special 
    792    case, the value "*" matches any current entity of the resource. 
     792   case, the value "*" matches any current representation of the resource. 
    793793</t> 
    794794<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="If-Match"/><iref primary="true" item="Grammar" subitem="If-Match-v"/> 
     
    797797</artwork></figure> 
    798798<t> 
    799    If any of the entity tags match the entity tag of the representation that 
     799   If any of the entity-tags match the entity-tag of the representation that 
    800800   would have been returned in the response to a similar GET request 
    801801   (without the If-Match header) on that resource, or if "*" is given 
    802    and any current entity exists for that resource, then the server &MAY; 
     802   and any current representation exists for that resource, then the server &MAY; 
    803803   perform the requested method as if the If-Match header field did not 
    804804   exist. 
    805805</t> 
    806806<t> 
    807    If none of the entity tags match, or if "*" is given and no current 
     807   If none of the entity-tags match, or if "*" is given and no current 
    808808   representation exists, the server &MUST-NOT; perform the requested method, and 
    809809   &MUST; return a 412 (Precondition Failed) response. This behavior is 
     
    827827   If-Match header field to signal that the request method &MUST-NOT; be 
    828828   applied if the representation corresponding to the If-Match value (a single 
    829    entity tag) is no longer a representation of that resource. This 
     829   entity-tag) is no longer a representation of that resource. This 
    830830   allows the user to indicate that they do not wish the request to be 
    831831   successful if the resource has been changed without their knowledge. 
     
    936936<t> 
    937937   The "If-None-Match" request-header field is used to make a request method 
    938    conditional. A client that has one or more entities previously 
    939    obtained from the resource can verify that none of those entities is 
    940    current by including a list of their associated entity tags in the 
     938   conditional. A client that has one or more representations previously 
     939   obtained from the resource can verify that none of those representations is 
     940   current by including a list of their associated entity-tags in the 
    941941   If-None-Match header field. 
    942942</t> 
     
    948948</t> 
    949949<t> 
    950    As a special case, the value "*" matches any current entity of the 
     950   As a special case, the value "*" matches any current representation of the 
    951951   resource. 
    952952</t> 
     
    956956</artwork></figure> 
    957957<t> 
    958    If any of the entity tags match the entity tag of the representation that 
     958   If any of the entity-tags match the entity-tag of the representation that 
    959959   would have been returned in the response to a similar GET request 
    960960   (without the If-None-Match header) on that resource, or if "*" is 
     
    970970</t> 
    971971<t> 
    972    If none of the entity tags match, then the server &MAY; perform the 
     972   If none of the entity-tags match, then the server &MAY; perform the 
    973973   requested method as if the If-None-Match header field did not exist, 
    974974   but &MUST; also ignore any If-Modified-Since header field(s) in the 
    975    request. That is, if no entity tags match, then the server &MUST-NOT; 
     975   request. That is, if no entity-tags match, then the server &MUST-NOT; 
    976976   return a 304 (Not Modified) response. 
    977977</t> 
     
    10751075   of the origin server and the nature of the original resource. For 
    10761076   files, it may be just the file system last-modified time. For 
    1077    entities with dynamically included parts, it may be the most recent 
     1077   representations with dynamically included parts, it may be the most recent 
    10781078   of the set of last-modify times for its component parts. For database 
    10791079   gateways, it may be the last-update time stamp of the record. For 
     
    10911091   as close as possible to the time that it generates the Date value of 
    10921092   its response. This allows a recipient to make an accurate assessment 
    1093    of the entity's modification time, especially if the representation changes 
     1093   of the representation's modification time, especially if the representation changes 
    10941094   near the time that the response is generated. 
    10951095</t> 
     
    14901490<section title="Changes from RFC 2616" anchor="changes.from.rfc.2616"> 
    14911491<t> 
    1492   Allow weak entity tags in all requests except range requests (Sections 
     1492  Allow weak entity-tags in all requests except range requests (Sections 
    14931493  <xref target="weak.and.strong.validators" format="counter"/> and 
    14941494  <xref target="header.if-none-match" format="counter"/>). 
  • draft-ietf-httpbis/latest/p5-range.xml

    r866 r874  
    316316<t> 
    317317   HTTP/1.1 allows a client to request that only part (a range of) the 
    318    response entity be included within the response. HTTP/1.1 uses range 
     318   representation be included within the response. HTTP/1.1 uses range 
    319319   units in the Range (<xref target="header.range"/>) and Content-Range (<xref target="header.content-range"/>) 
    320    header fields. An entity can be broken down into subranges according 
     320   header fields. A representation can be broken down into subranges according 
    321321   to various structural units. 
    322322</t> 
     
    412412<section title="Combining Ranges" anchor="combining.byte.ranges"> 
    413413<t> 
    414    A response might transfer only a subrange of an entity-body, either because 
     414   A response might transfer only a subrange of a representation, either because 
    415415   the request included one or more Range specifications, or because  
    416    a connection was broken prematurely. 
     416   a connection closed prematurely. 
    417417   After several such transfers, a cache might have received several  
    418    ranges of the same entity-body. 
     418   ranges of the same representation. 
    419419</t> 
    420420<t> 
     
    498498  <x:anchor-alias value="other-range-resp-spec"/> 
    499499<t> 
    500    The "Content-Range" entity-header field is sent with a partial entity-body to 
    501    specify where in the full entity-body the partial body should be 
     500   The "Content-Range" entity-header field is sent with a partial representation to 
     501   specify where in the full representation the partial body should be 
    502502   applied. Range units are defined in <xref target="range.units"/>. 
    503503</t> 
     
    522522</artwork></figure> 
    523523<t> 
    524    The header &SHOULD; indicate the total length of the full entity-body, 
     524   The header &SHOULD; indicate the total length of the full representation, 
    525525   unless this length is unknown or difficult to determine. The asterisk 
    526526   "*" character means that the instance-length is unknown at the time 
     
    617617   invalid, the server &SHOULD; treat the request as if the invalid Range 
    618618   header field did not exist. (Normally, this means return a 200 
    619    response containing the full entity). 
     619   response containing the full representation). 
    620620</t> 
    621621<t> 
     
    643643  <x:anchor-alias value="If-Range-v"/> 
    644644<t> 
    645    If a client has a partial copy of an entity in its cache, and wishes 
    646    to have an up-to-date copy of the entire entity in its cache, it 
     645   If a client has a partial copy of a representation in its cache, and wishes 
     646   to have an up-to-date copy of the entire representation in its cache, it 
    647647   could use the Range request-header with a conditional GET (using 
    648648   either or both of If-Unmodified-Since and If-Match.) However, if the 
     
    662662</artwork></figure> 
    663663<t> 
    664    If the client has no entity tag for a representation, but does have a Last-Modified 
     664   If the client has no entity-tag for a representation, but does have a Last-Modified 
    665665   date, it &MAY; use that date in an If-Range header. (The 
    666666   server can distinguish between a valid HTTP-date and any form of 
     
    671671</t> 
    672672<t> 
    673    If the entity tag given in the If-Range header matches the current 
     673   If the entity-tag given in the If-Range header matches the current 
    674674   cache validator for the representation, then the server &SHOULD; provide the 
    675675   specified sub-range of the representation using a 206 (Partial Content) 
     
    744744   A suffix-byte-range-spec is used to specify the suffix of the 
    745745   representation body, of a length given by the suffix-length value. (That is, 
    746    this form specifies the last N bytes of an entity-body.) If the 
     746   this form specifies the last N bytes of a representation.) If the 
    747747   representation is shorter than the specified suffix-length, the entire 
    748748   representation is used. 
     
    751751   If a syntactically valid byte-range-set includes at least one byte-range-spec 
    752752   whose first-byte-pos is less than the current length of 
    753    the entity-body, or at least one suffix-byte-range-spec with a non-zero 
     753   the representation, or at least one suffix-byte-range-spec with a non-zero 
    754754   suffix-length, then the byte-range-set is satisfiable. 
    755755   Otherwise, the byte-range-set is unsatisfiable. If the byte-range-set 
     
    760760</t> 
    761761<t> 
    762    Examples of byte-ranges-specifier values (assuming an entity-body of 
     762   Examples of byte-ranges-specifier values (assuming a representation of 
    763763   length 10000): 
    764764  <list style="symbols"> 
     
    820820   possible, since Range supports efficient recovery from partially 
    821821   failed transfers, and supports efficient partial retrieval of large 
    822    entities. 
     822   representations. 
    823823</t> 
    824824<t> 
    825825   If the server supports the Range header and the specified range or 
    826    ranges are appropriate for the entity: 
     826   ranges are appropriate for the representation: 
    827827  <list style="symbols"> 
    828828     <t>The presence of a Range header in an unconditional GET modifies 
     
    845845<t> 
    846846   If a proxy that supports ranges receives a Range request, forwards 
    847    the request to an inbound server, and receives an entire entity in 
     847   the request to an inbound server, and receives an entire representation in 
    848848   reply, it &SHOULD; only return the requested range to its client. It 
    849849   &SHOULD; store the entire received response in its cache if that is 
  • draft-ietf-httpbis/latest/p6-cache.xml

    r866 r874  
    271271  <x:dfn>explicit expiration time</x:dfn> 
    272272  <list> 
    273     <t>The time at which the origin server intends that an entity should no longer be 
     273    <t>The time at which the origin server intends that a representation should no longer be 
    274274      returned by a cache without further validation.</t> 
    275275  </list> 
     
    324324  <x:dfn>validator</x:dfn> 
    325325  <list> 
    326     <t>A protocol element (e.g., an entity tag or a Last-Modified time) that is used to find 
     326    <t>A protocol element (e.g., an entity-tag or a Last-Modified time) that is used to find 
    327327      out whether a stored response has an equivalent copy of a representation.</t> 
    328328  </list> 
     
    929929  The updated response can <cref anchor="TODO-is-req">requirement?</cref> be used to replace the   
    930930  stored response in cache. In the case of a 206 response, the combined   
    931   entity-body &MAY; be stored. 
     931  representation &MAY; be stored. 
    932932</t> 
    933933<t> 
     
    11071107    <t>The no-transform request directive indicates that an intermediate cache or proxy 
    11081108      &MUST-NOT; change the Content-Encoding, Content-Range or Content-Type request 
    1109       headers, nor the request entity-body.</t> 
     1109      headers, nor the request representation.</t> 
    11101110  </list> 
    11111111</t> 
     
    12631263    <t>The no-transform response directive indicates that an intermediate cache or proxy 
    12641264      &MUST-NOT; change the Content-Encoding, Content-Range or Content-Type response 
    1265       headers, nor the response entity-body.</t> 
     1265      headers, nor the response representation.</t> 
    12661266  </list> 
    12671267</t> 
     
    15851585  214 Transformation applied 
    15861586  <list> 
    1587     <t>&MUST; be added by an intermediate cache or proxy if it applies any 
    1588       transformation changing the content-coding (as specified in the Content-Encoding 
    1589       header) or media-type (as specified in the Content-Type header) of the response, or 
    1590       the entity-body of the response, unless this Warning code already appears in the 
    1591       response.</t> 
     1587    <t>&MUST; be added by an intermediate proxy if it applies any 
     1588      transformation to the representation, such as changing the content-coding, 
     1589      media-type, or modifying the representation data, unless this Warning code 
     1590      already appears in the response.</t> 
    15921591  </list> 
    15931592</t> 
     
    16071606<t> 
    16081607  User agents often have history mechanisms, such as "Back" buttons and history lists, that 
    1609   can be used to redisplay an entity retrieved earlier in a session. 
     1608  can be used to redisplay a representation retrieved earlier in a session. 
    16101609</t> 
    16111610<t> 
  • draft-ietf-httpbis/latest/p7-auth.xml

    r848 r874  
    310310   prior response, and the user agent has already attempted 
    311311   authentication at least once, then the user &SHOULD; be presented the 
    312    entity that was given in the response, since that entity might 
     312   representation that was given in the response, since that representation might 
    313313   include relevant diagnostic information. HTTP access authentication 
    314314   is explained in "HTTP Authentication: Basic and Digest Access 
Note: See TracChangeset for help on using the changeset viewer.