Ignore:
Timestamp:
02/09/12 06:07:22 (8 years ago)
Author:
fielding@…
Message:

(editorial) define representation before methods

File:
1 edited

Legend:

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

    r1848 r1849  
    288288</section>
    289289
     290<section title="Representation" anchor="representation">
     291<iref item="representation"/>
     292<t>
     293   A "<x:dfn>representation</x:dfn>" is information in a format that can be readily
     294   communicated from one party to another.  A resource representation
     295   is information that reflects the state of that resource, as observed
     296   at some point in the past (e.g., in a response to GET) or to be
     297   desired at some point in the future (e.g., in a PUT request).
     298</t>
     299<t>
     300   Most, but not all, representations transferred via HTTP are intended
     301   to be a representation of the target resource (the resource identified
     302   by the effective request URI).  The precise semantics of a representation
     303   are determined by the type of message (request or response), the request
     304   method, the response status code, and the representation metadata. For
     305   example, the above semantic is true for the representation in any
     306   <x:ref>200 (OK)</x:ref> response to GET and for the representation in any PUT request.
     307   A 200 response to PUT, in contrast, contains either a representation
     308   that describes the successful action or a representation of the target
     309   resource, with the latter indicated by a <x:ref>Content-Location</x:ref>
     310   header field with the same value as the effective request URI.  Likewise,
     311   response messages with an error status code usually contain a representation
     312   that describes the error and what next steps are suggested for resolving it.
     313</t>
     314<t>
     315   Request and Response messages &MAY; transfer a representation if not otherwise
     316   restricted by the request method or response status code. A representation
     317   consists of metadata (representation header fields) and data (representation
     318   body).  When a complete or partial representation is enclosed in an HTTP message,
     319   it is referred to as the payload of the message.
     320</t>
     321<t>
     322   A representation body is only present in a message when a message body is
     323   present, as described in &message-body;. The representation body is obtained
     324   from the message body by decoding any <x:ref>Transfer-Encoding</x:ref> that
     325   might have been applied to ensure safe and proper transfer of the message.
     326</t>
     327
     328<section title="Identifying the Resource Associated with a Representation" anchor="identifying.response.associated.with.representation">
     329<t>
     330   It is sometimes necessary to determine an identifier for the resource
     331   associated with a representation.
     332</t>
     333<t>
     334   An HTTP request representation, when present, is always associated with an
     335   anonymous (i.e., unidentified) resource.
     336</t>
     337<t>
     338   In the common case, an HTTP response is a representation of the target
     339   resource (see &effective-request-uri;). However, this is not always the
     340   case. To determine the URI of the resource a response is associated with,
     341   the following rules are used (with the first applicable one being selected):
     342</t>
     343<t><list style="numbers">
     344   <t>If the response status code is <x:ref>200 (OK)</x:ref> or <x:ref>203
     345   (Non-Authoritative Information)</x:ref> and the request method was GET,
     346   the response payload is a representation of the target resource.</t>
     347   <t>If the response status code is <x:ref>204 (No Content)</x:ref>,
     348   <x:ref>206 (Partial Content)</x:ref>, or <x:ref>304 (Not Modified)</x:ref>
     349   and the request method was GET or HEAD, the response payload is a partial
     350   representation of the target resource.</t>
     351   <t>If the response has a <x:ref>Content-Location</x:ref> header field, and
     352   that URI is the same as the effective request URI, the response payload is a
     353   representation of the target resource.</t>
     354   <t>If the response has a <x:ref>Content-Location</x:ref> header field, and
     355   that URI is not the same as the effective request URI, then the response
     356   asserts that its payload is a representation of the resource identified by
     357   the Content-Location URI. However, such an assertion cannot be trusted unless
     358   it can be verified by other means (not defined by HTTP).</t>
     359   <t>Otherwise, the response is a representation of an anonymous (i.e.,
     360   unidentified) resource.</t>
     361</list></t>
     362<t>
     363  <cref anchor="TODO-req-uri">
     364   The comparison function is going to have to be defined somewhere,
     365   because we already need to compare URIs for things like cache invalidation.</cref>
     366</t>
     367</section>
     368
     369<section title="Representation Header Fields" anchor="representation.header.fields">
     370  <x:anchor-alias value="representation-header"/>
     371<t>
     372   Representation header fields define metadata about the representation data
     373   enclosed in the message body or, if no message body is present, about
     374   the representation that would have been transferred in a <x:ref>200 (OK)</x:ref>
     375   response to a simultaneous GET request with the same effective request URI.
     376</t>
     377<t>
     378   The following header fields are defined as representation metadata:
     379</t>
     380<texttable align="left">
     381  <ttcol>Header Field Name</ttcol>
     382  <ttcol>Defined in...</ttcol>
     383
     384  <c>Content-Encoding</c> <c><xref target="header.content-encoding"/></c>
     385  <c>Content-Language</c> <c><xref target="header.content-language"/></c>
     386  <c>Content-Location</c> <c><xref target="header.content-location"/></c>
     387  <c>Content-Type</c> <c><xref target="header.content-type"/></c>
     388  <c>Expires</c> <c>&header-expires;</c>
     389</texttable>
     390<t><iref primary="true" item="selected representation"/>
     391   We use the term "<x:dfn>selected representation</x:dfn>" to refer to the
     392   the current representation of a target resource that would have been
     393   selected in a successful response if the same request had used the
     394   method GET and excluded any conditional request header fields.
     395</t>
     396<t>
     397   Additional header fields define metadata about the selected
     398   representation, which might differ from the representation included
     399   in the message for responses to some state-changing methods.
     400   The following header fields are defined as selected representation
     401   metadata:
     402</t>
     403<texttable align="left">
     404  <ttcol>Header Field Name</ttcol>
     405  <ttcol>Defined in...</ttcol>
     406
     407  <c>ETag</c> <c>&header-etag;</c>
     408  <c>Last-Modified</c> <c>&header-last-modified;</c>
     409</texttable>
     410</section>
     411
     412<section title="Representation Data" anchor="representation.data">
     413  <x:anchor-alias value="representation-data"/>
     414<t>
     415   The representation body associated with an HTTP message is
     416   either provided as the payload body of the message or
     417   referred to by the message semantics and the effective request
     418   URI.  The representation data is in a format and encoding defined by
     419   the representation metadata header fields.
     420</t>
     421<t>
     422   The data type of the representation data is determined via the header fields
     423   <x:ref>Content-Type</x:ref> and <x:ref>Content-Encoding</x:ref>.
     424   These define a two-layer, ordered encoding model:
     425</t>
     426<figure><artwork type="example">
     427  representation-data := Content-Encoding( Content-Type( bits ) )
     428</artwork></figure>
     429<t>
     430   <x:ref>Content-Type</x:ref> specifies the media type of the underlying data,
     431   which defines both the data format and how that data &SHOULD; be processed
     432   by the recipient (within the scope of the request method semantics).
     433   Any HTTP/1.1 message containing a payload body &SHOULD; include a
     434   Content-Type header field defining the media type of the associated
     435   representation unless that metadata is unknown to the sender.
     436   If the Content-Type header field is not present, it indicates that
     437   the sender does not know the media type of the representation;
     438   recipients &MAY; either assume that the media type is
     439   "application/octet-stream" (<xref target="RFC2046" x:fmt="," x:sec="4.5.1"/>)
     440   or examine the content to determine its type.
     441</t>
     442<t>
     443   In practice, resource owners do not always properly configure their origin
     444   server to provide the correct Content-Type for a given representation,
     445   with the result that some clients will examine a response body's content
     446   and override the specified type.
     447   Clients that do so risk drawing incorrect conclusions, which might expose
     448   additional security risks (e.g., "privilege escalation").  Furthermore,
     449   it is impossible to determine the sender's intent by examining the data
     450   format: many data formats match multiple media types that differ only in
     451   processing semantics.  Implementers are encouraged to provide a means of
     452   disabling such "content sniffing" when it is used.
     453</t>
     454<t>
     455   <x:ref>Content-Encoding</x:ref> is used to indicate any additional content
     456   codings applied to the data, usually for the purpose of data
     457   compression, that are a property of the representation.  If
     458   Content-Encoding is not present, then there is no additional
     459   encoding beyond that defined by the <x:ref>Content-Type</x:ref> header field.
     460</t>
     461</section>
     462</section>
     463
    290464<section title="Request Methods" anchor="methods">
    291465
     
    24872661</section>
    24882662</section>
    2489 
    2490 <section title="Representation" anchor="representation">
    2491 <iref item="representation"/>
    2492 <t>
    2493    A "<x:dfn>representation</x:dfn>" is information in a format that can be readily
    2494    communicated from one party to another.  A resource representation
    2495    is information that reflects the state of that resource, as observed
    2496    at some point in the past (e.g., in a response to GET) or to be
    2497    desired at some point in the future (e.g., in a PUT request).
    2498 </t>
    2499 <t>
    2500    Most, but not all, representations transferred via HTTP are intended
    2501    to be a representation of the target resource (the resource identified
    2502    by the effective request URI).  The precise semantics of a representation
    2503    are determined by the type of message (request or response), the request
    2504    method, the response status code, and the representation metadata. For
    2505    example, the above semantic is true for the representation in any
    2506    <x:ref>200 (OK)</x:ref> response to GET and for the representation in any PUT request.
    2507    A 200 response to PUT, in contrast, contains either a representation
    2508    that describes the successful action or a representation of the target
    2509    resource, with the latter indicated by a <x:ref>Content-Location</x:ref>
    2510    header field with the same value as the effective request URI.  Likewise,
    2511    response messages with an error status code usually contain a representation
    2512    that describes the error and what next steps are suggested for resolving it.
    2513 </t>
    2514 <t>
    2515    Request and Response messages &MAY; transfer a representation if not otherwise
    2516    restricted by the request method or response status code. A representation
    2517    consists of metadata (representation header fields) and data (representation
    2518    body).  When a complete or partial representation is enclosed in an HTTP message,
    2519    it is referred to as the payload of the message.
    2520 </t>
    2521 <t>
    2522    A representation body is only present in a message when a message body is
    2523    present, as described in &message-body;. The representation body is obtained
    2524    from the message body by decoding any <x:ref>Transfer-Encoding</x:ref> that
    2525    might have been applied to ensure safe and proper transfer of the message.
    2526 </t>
    2527 
    2528 <section title="Identifying the Resource Associated with a Representation" anchor="identifying.response.associated.with.representation">
    2529 <t>
    2530    It is sometimes necessary to determine an identifier for the resource
    2531    associated with a representation.
    2532 </t>
    2533 <t>
    2534    An HTTP request representation, when present, is always associated with an
    2535    anonymous (i.e., unidentified) resource.
    2536 </t>
    2537 <t>
    2538    In the common case, an HTTP response is a representation of the target
    2539    resource (see &effective-request-uri;). However, this is not always the
    2540    case. To determine the URI of the resource a response is associated with,
    2541    the following rules are used (with the first applicable one being selected):
    2542 </t>
    2543 <t><list style="numbers">
    2544    <t>If the response status code is <x:ref>200 (OK)</x:ref> or <x:ref>203
    2545    (Non-Authoritative Information)</x:ref> and the request method was GET,
    2546    the response payload is a representation of the target resource.</t>
    2547    <t>If the response status code is <x:ref>204 (No Content)</x:ref>,
    2548    <x:ref>206 (Partial Content)</x:ref>, or <x:ref>304 (Not Modified)</x:ref>
    2549    and the request method was GET or HEAD, the response payload is a partial
    2550    representation of the target resource.</t>
    2551    <t>If the response has a <x:ref>Content-Location</x:ref> header field, and
    2552    that URI is the same as the effective request URI, the response payload is a
    2553    representation of the target resource.</t>
    2554    <t>If the response has a <x:ref>Content-Location</x:ref> header field, and
    2555    that URI is not the same as the effective request URI, then the response
    2556    asserts that its payload is a representation of the resource identified by
    2557    the Content-Location URI. However, such an assertion cannot be trusted unless
    2558    it can be verified by other means (not defined by HTTP).</t>
    2559    <t>Otherwise, the response is a representation of an anonymous (i.e.,
    2560    unidentified) resource.</t>
    2561 </list></t>
    2562 <t>
    2563   <cref anchor="TODO-req-uri">
    2564    The comparison function is going to have to be defined somewhere,
    2565    because we already need to compare URIs for things like cache invalidation.</cref>
    2566 </t>
    2567 </section>
    2568 
    2569 <section title="Representation Header Fields" anchor="representation.header.fields">
    2570   <x:anchor-alias value="representation-header"/>
    2571 <t>
    2572    Representation header fields define metadata about the representation data
    2573    enclosed in the message body or, if no message body is present, about
    2574    the representation that would have been transferred in a <x:ref>200 (OK)</x:ref>
    2575    response to a simultaneous GET request with the same effective request URI.
    2576 </t>
    2577 <t>
    2578    The following header fields are defined as representation metadata:
    2579 </t>
    2580 <texttable align="left">
    2581   <ttcol>Header Field Name</ttcol>
    2582   <ttcol>Defined in...</ttcol>
    2583 
    2584   <c>Content-Encoding</c> <c><xref target="header.content-encoding"/></c>
    2585   <c>Content-Language</c> <c><xref target="header.content-language"/></c>
    2586   <c>Content-Location</c> <c><xref target="header.content-location"/></c>
    2587   <c>Content-Type</c> <c><xref target="header.content-type"/></c>
    2588   <c>Expires</c> <c>&header-expires;</c>
    2589 </texttable>
    2590 <t><iref primary="true" item="selected representation"/>
    2591    We use the term "<x:dfn>selected representation</x:dfn>" to refer to the
    2592    the current representation of a target resource that would have been
    2593    selected in a successful response if the same request had used the
    2594    method GET and excluded any conditional request header fields.
    2595 </t>
    2596 <t>
    2597    Additional header fields define metadata about the selected
    2598    representation, which might differ from the representation included
    2599    in the message for responses to some state-changing methods.
    2600    The following header fields are defined as selected representation
    2601    metadata:
    2602 </t>
    2603 <texttable align="left">
    2604   <ttcol>Header Field Name</ttcol>
    2605   <ttcol>Defined in...</ttcol>
    2606 
    2607   <c>ETag</c> <c>&header-etag;</c>
    2608   <c>Last-Modified</c> <c>&header-last-modified;</c>
    2609 </texttable>
    2610 </section>
    2611 
    2612 <section title="Representation Data" anchor="representation.data">
    2613   <x:anchor-alias value="representation-data"/>
    2614 <t>
    2615    The representation body associated with an HTTP message is
    2616    either provided as the payload body of the message or
    2617    referred to by the message semantics and the effective request
    2618    URI.  The representation data is in a format and encoding defined by
    2619    the representation metadata header fields.
    2620 </t>
    2621 <t>
    2622    The data type of the representation data is determined via the header fields
    2623    <x:ref>Content-Type</x:ref> and <x:ref>Content-Encoding</x:ref>.
    2624    These define a two-layer, ordered encoding model:
    2625 </t>
    2626 <figure><artwork type="example">
    2627   representation-data := Content-Encoding( Content-Type( bits ) )
    2628 </artwork></figure>
    2629 <t>
    2630    <x:ref>Content-Type</x:ref> specifies the media type of the underlying data,
    2631    which defines both the data format and how that data &SHOULD; be processed
    2632    by the recipient (within the scope of the request method semantics).
    2633    Any HTTP/1.1 message containing a payload body &SHOULD; include a
    2634    Content-Type header field defining the media type of the associated
    2635    representation unless that metadata is unknown to the sender.
    2636    If the Content-Type header field is not present, it indicates that
    2637    the sender does not know the media type of the representation;
    2638    recipients &MAY; either assume that the media type is
    2639    "application/octet-stream" (<xref target="RFC2046" x:fmt="," x:sec="4.5.1"/>)
    2640    or examine the content to determine its type.
    2641 </t>
    2642 <t>
    2643    In practice, resource owners do not always properly configure their origin
    2644    server to provide the correct Content-Type for a given representation,
    2645    with the result that some clients will examine a response body's content
    2646    and override the specified type.
    2647    Clients that do so risk drawing incorrect conclusions, which might expose
    2648    additional security risks (e.g., "privilege escalation").  Furthermore,
    2649    it is impossible to determine the sender's intent by examining the data
    2650    format: many data formats match multiple media types that differ only in
    2651    processing semantics.  Implementers are encouraged to provide a means of
    2652    disabling such "content sniffing" when it is used.
    2653 </t>
    2654 <t>
    2655    <x:ref>Content-Encoding</x:ref> is used to indicate any additional content
    2656    codings applied to the data, usually for the purpose of data
    2657    compression, that are a property of the representation.  If
    2658    Content-Encoding is not present, then there is no additional
    2659    encoding beyond that defined by the <x:ref>Content-Type</x:ref> header field.
    2660 </t>
    2661 </section>
    2662 </section>
    2663 
    2664 
    26652663
    26662664<section title="Content Negotiation" anchor="content.negotiation">
Note: See TracChangeset for help on using the changeset viewer.