One document matched: draft-snell-link-method-04.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-23.xml'>
  <!ENTITY part6 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-httpbis-p6-cache-23.xml'>
]>
<?rfc toc="yes"?> 
<?rfc strict="yes"?> 
<?rfc symrefs="yes" ?> 
<?rfc sortrefs="yes"?> 
<?rfc compact="yes"?> 
<rfc category="std" ipr="trust200811" docName="draft-snell-link-method-04"> 
  <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="September" 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"/>.
    </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
      the resource identified by the effective request URI and one or more other 
      resources. Metadata contained within Link header fields <xref target="RFC5988"/>
      provide information about which other resources are being connected to the 
      target and the type of relationship being established. A payload 
      within a LINK request has no defined semantics.
    </t>
    
    <t>
      LINK requests are idempotent. For any pair of resources, exactly one 
      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 requests 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 can contain multiple Link header fields, each
      of which establishes a separate, independent relationship with the 
      target resource. In such cases, the server MUST either create all of
      the relationships or not create any of them.
    </t>
    
  </section>
  
  <section title="UNLINK" anchor="unlink">
  
    <t>
      The UNLINK method is used to remove one or more relationships
      between the resource identified by the effective request URI and 
      other resources. Metadata contained within Link header fields 
      <xref target="RFC5988"/> provide the information about the 
      relationships that are to be removed. A payload within an UNLINK request 
      has no defined semantics.
    </t>
    
    <t>
      UNLINK request messages are idempotent but are not safe. 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 either remove the entire set of relationships atomically
      or not remove any of them.
    </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="mention"
    ]]></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>
      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;
  &rfc5988;
  &part2;
  &part6;
</references>
<references title="Informational References">
  &rfc2068;
</references>
</back>
</rfc>