One document matched: draft-snell-link-method-02.xml

<?xml version="1.0"?> 
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [ 
  <!ENTITY rfc2119 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
  <!ENTITY rfc2068 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2068.xml'>
  <!ENTITY rfc5988 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5988.xml'>
  <!ENTITY part2 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-httpbis-p2-semantics-22.xml'>
  <!ENTITY part4 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-httpbis-p4-conditional-22.xml'>
  <!ENTITY part6 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-httpbis-p6-cache-22.xml'>
]>
<?rfc toc="yes"?> 
<?rfc strict="yes"?> 
<?rfc symrefs="yes" ?> 
<?rfc sortrefs="yes"?> 
<?rfc compact="yes"?> 
<rfc category="info" ipr="trust200811" docName="draft-snell-link-method-02"> 
  <front> 
    <title abbrev="HTTP Link and Unlink Methods"> 
      HTTP Link and Unlink Methods
    </title> 
 
    <author initials="J.M." surname="Snell" fullname="James M Snell"> 
      <address> 
        <email>jasnell@gmail.com</email> 
      </address> 
    </author> 
    
    <date month="April" year="2013" /> 
 
    <area>Applications</area> 
    <!-- workgroup>Individual Submission</workgroup--> 
    <keyword>I-D</keyword> 
    <keyword>json</keyword>
    <keyword>predicate</keyword>
 
    <abstract> 
      <t>This specification defines the semantics of the Link and Unlink
      HTTP methods.</t> 
    </abstract> 
 
  </front> 
  
  <middle> 

  <section anchor="intro" title="Introduction"> 

    <t>This specification updates the HTTP LINK and UNLINK methods originally
      defined in <xref target="RFC2068"/>. These were originally defined as 
      "additional request methods" that were later dropped entirely from 
      follow-on iterations of the HTTP specification due to previous lack of  
      interest or use.</t>
      
    <t>TODO: Fill in explanation as to why this is needed.</t>
  
    <t>In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", 
    "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 
    are to be  interpreted as described in <xref target="RFC2119" />.</t> 

  </section> 
  
  <section title="LINK" anchor="link">
  
    <t>The LINK method is used to establish one or more relationships between
    an existing resource identified by the effective request URI and other 
    resources. Metadata contained within Link header fields <xref target="RFC5988"/>
    provide the information about which other resources are being connected to the 
    target resource and the type of relationship being established. A payload 
    within a LINK request message has no defined semantics.</t>
    
    <t>The semantics of the LINK method change to a "conditional LINK" if the
    request message includes an If-Modified-Since, If-Unmodified-Since,
    If-Match, If-None-Match, or If-Range header field (<xref target="I-D.ietf-httpbis-p4-conditional"/>).  A
    conditional LINK requests that the relationship be established only under the 
    circumstances described by the conditional header field(s).</t>

    <t>LINK request messages are idempotent. For any pair of resources, only a 
    single relationship of any given type can exist. However, multiple relationships 
    of different types can be established between the same pair of resources.</t>
    
    <t>LINK request messages are not safe, however. Establishing a relationship
    causes an inherent change to the state of the target resource.</t>
    
    <t>Responses to LINK requests are not cacheable. If a LINK
    request passes through a cache that has one or more stored responses
    for the effective request URI, those stored responses will be
    invalidated (see Section 6 of <xref target="I-D.ietf-httpbis-p6-cache"/>).</t>

    <t>A single LINK request message can contain multiple Link header fields, each
    of which establishes a separate relationship with the target resource. 
    In such cases, the server MUST accept the entire set of relationships atomically. 
    If any of the specified relationships cannot be created, the server MUST NOT
    create any of them.</t>
    
    <t>A successful response to a Link request that results in either the creation 
    or modification of a relationship SHOULD be 200 (OK) if the response includes a 
    representation describing the status, 201 (Created) if the action results in the 
    creation of a new resource that represents the newly established relationship, 
    202 (Accepted) if the action has not yet been enacted, or 204 (No Content) if the 
    action has been enacted but the response does not include a representation.</t>
    
    <t>The LINK method MAY be overridden by human intervention (or
    other means) on the origin server.  The client cannot be guaranteed
    that the operation has been carried out, even if the status code
    returned from the origin server indicates that the action has been
    completed successfully.  However, the server SHOULD NOT indicate
    success unless, at the time the response is given, it intends to
    create or update the specified relationships.</t>
    
    <t>If the LINK request message attempts to create or update an existing 
    relationship and the server does not intend to comply with the request for 
    any reason other than a client or server error, the server can return a 
    304 (Not Modified) response to indicate that no modifications have been made.</t>
        
  </section>
  
  <section title="UNLINK" anchor="unlink">
  
    <t>The UNLINK method is used to remove one or more relationships
    between the existing resource identified by the effective request 
    URI and other resources. Metadata contained within Link header fields <xref target="RFC5988"/>
    provide the information about the resources to which relationships of a specific type 
    are to be removed. A payload within an UNLINK request message has no defined semantics.</t>
    
    <t>The semantics of the UNLINK method change to a "conditional UNLINK" if the
    request message includes an If-Modified-Since, If-Unmodified-Since,
    If-Match, If-None-Match, or If-Range header field (<xref target="I-D.ietf-httpbis-p4-conditional"/>).  A
    conditional UNLINK requests that the relationship be removed only under the 
    circumstances described by the conditional header field(s).</t>

    <t>UNLINK request messages are idempotent.</t>
    
    <t>UNLINK request messages are not safe, however. Removing a relationship
    causes an inherent change to the state of the target resource.</t>
    
    <t>Responses to UNLINK requests are not cacheable. If an UNLINK
    request passes through a cache that has one or more stored responses
    for the effective request URI, those stored responses will be
    invalidated (see Section 6 of <xref target="I-D.ietf-httpbis-p6-cache"/>).</t>

    <t>A single UNLINK request message can contain multiple Link header fields, each
    of which identifies a separate relationship to remove. In such cases, the 
    server MUST remove the entire set of relationships atomically. If any of the specified 
    relationships cannot be removed, the server MUST NOT remove any of them.</t>

    <t>A successful response indicating the removing of the relationship SHOULD be 200 (OK) 
    if the response includes a representation describing the status, 202 (Accepted) 
    if the action has not yet been enacted, or 204 (No Content) if the action has 
    been enacted but the response does not include a representation.</t>
    
    <t>The UNLINK method MAY be overridden by human intervention (or
    other means) on the origin server.  The client cannot be guaranteed
    that the operation has been carried out, even if the status code
    returned from the origin server indicates that the action has been
    completed successfully.  However, the server SHOULD NOT indicate
    success unless, at the time the response is given, it intends to
    remove the specified relationships.</t>

    <t>If the UNLINK request message attempts to remove an existing relationship
    and the server does not intend to remove or otherwise alter the existing  
    relationship for any reason other than a client or server error, the server can 
    return a 304 (Not Modified) response to indicate that no modifications have 
    been made.</t>
    
  </section>

  <section title="Relationship to other HTTP Methods and Discoverability of Links">
    
    <t>The use of the LINK and UNLINK request methods to manage relationships 
    between resources has no direct bearing on the use or appearance of Link 
    header fields within any other HTTP request or response message 
    involving the same effective request URI. Nor do the methods have any 
    direct normative impact on the use of link-like structures within the resource
    representations returned by a server for any particular resource.</t>
    
    <t>Whether and how to represent relationships managed using LINK 
    and UNLINK is left solely at the discretion of the server implementation.</t>
    
    <t>This specification does not define a means of discovering or 
    enumerating the relationships that have been established using the 
    LINK request method.</t>
    
  </section>

  <section title="Example" anchor="example">
  
    <t>There exists a broad range of possible use cases for the LINK and UNLINK
    methods. The examples that follow illustrate a subset of those cases.</t>
  
    <figure><preamble>Example 1: Creating two separate links between an image
    and the profiles of two people associated with the image:</preamble><artwork><![CDATA[
  LINK /images/my_dog.jpg HTTP/1.1
  Host: example.org
  Link: <http://example.com/profiles/joe>; rel="tag"
  Link: <http://example.com/profiles/sally>; rel="tag"
    ]]></artwork></figure>
    
    <figure><preamble>Example 2: Removing an existing Link relationship between
    two resources:</preamble><artwork><![CDATA[
  UNLINK /images/my_dog.jpg HTTP/1.1
  Host: example.org
  Link: <http://example.com/profiles/sally>; rel="tag"
    ]]></artwork></figure>
    
    <figure><preamble>Example 3: Establish a "pingback" or "trackback" style link to
    a blog entry about an article</preamble><artwork><![CDATA[
  LINK /articles/an_interesting_article HTTP/1.1
  Host: example.org
  Link: <http://example.com/my_blog_post>; rel="about"
    ]]></artwork></figure>
    
    <figure><preamble>Example 4: Establish a link between two semantically related
    resources:</preamble><artwork><![CDATA[
  LINK /some-resource HTTP/1.1
  Host: example.org
  Link: <http://example.com/schemas/my_schema>; rel="describedBy"
    ]]></artwork></figure>
    
    <figure><preamble>Example 5: Add an existing resource to a collection:</preamble><artwork><![CDATA[
  LINK /some-collection-resource HTTP/1.1
  Host: example.org
  Link: <http://example.com/my-member-resource>; rel="item"
    ]]></artwork></figure>
  
    <figure><preamble>Example 6: Link one resource to another that monitors its 
    current state (e.g. pub/sub)</preamble><artwork><![CDATA[
  LINK /my-resource HTTP/1.1
  Host: example.org
  Link: <http://example.com/my-monitor>; rel="monitor"
    ]]></artwork></figure>
    
  </section>

  <section title="Security Considerations">
    <t>The LINK and UNLINK methods are subject to the same general security considerations
    as all HTTP methods as described in <xref target="I-D.ietf-httpbis-p2-semantics"/>.</t>
    
    <t>Implementers need to be aware of the possible ways the LINK method can be 
    abused as a means of propagating inappropriate links to external resources. For 
    instance, the unregulated acceptance of LINK requests can be used as a vector for 
    spam or malware distribution.</t>
    
    <t>Because the LINK and UNLINK methods cause changes to a resource's state, the 
    server is responsible for determining the client's authorization to make such 
    changes.</t>
  </section>
  
</middle>
 
<back>
<references title="Normative References"> 
  &rfc2119;
  &rfc2068;
  &rfc5988;
  &part2;
  &part4;
  &part6;
</references>
  
</back>
</rfc>