One document matched: draft-snell-link-method-00.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-21.xml'>
  <!ENTITY part4 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-httpbis-p4-conditional-21.xml'>
  <!ENTITY part6 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-httpbis-p6-cache-21.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-00"> 
  <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="October" year="2012" /> 
 
    <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 Link 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 which other resources are being linked to the 
    target resource and the type of link 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 Link 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 Link of any given relation type can exist. However, multiple links 
    of different relation types can be established between those resources.</t>
    
    <t>LINK request messages are not safe, however, in that establishing a Link
    causes an inherent change to the state of the target resource.</t>
    
    <t>The response to a LINK request is cacheable and MAY be used to satisfy
    subsequent LINK requests (see <xref target="I-D.ietf-httpbis-p6-cache"/>). 
    However, caching such responses is not likely to provide any significant 
    benefit or be supported by existing infrastructure.</t>

    <t>A single LINK request message can contain multiple Link header fields, each
    of which establishes a separate Link relationship with the target resource. 
    In such cases, the server MUST accept the entire set of Links atomically. 
    If any of the specified Link relationships cannot be created, the server MUST NOT
    create any of the Links.</t>
    
    <t>A successful response 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 link, 
    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>
    
  </section>
  
  <section title="UNLINK" anchor="unlink">
  
    <t>The UNLINK method is used to remove one of more Link relationships of
    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 links 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 Link 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, in that removing a Link
    causes an inherent change to the state of the target resource.</t>
    
    <t>The response to an UNLINK request is cacheable and MAY be used to satisfy
    subsequent UNLINK requests (see <xref target="I-D.ietf-httpbis-p6-cache"/>). 
    However, caching such responses is not likely to provide any significant benefit 
    or be supported by existing infrastructure.</t>

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

    <t>A successful response 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 Links.</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 it's 
    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>