One document matched: draft-snell-link-method-07.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-24.xml'>
<!ENTITY part6 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-httpbis-p6-cache-24.xml'>
<!ENTITY part4 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-httpbis-p4-conditional-24.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-07">
<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="November" year="2013" />
<area>Applications</area>
<workgroup>Individual Submission</workgroup>
<keyword>I-D</keyword>
<keyword>http</keyword>
<keyword>link</keyword>
<keyword>unlink</keyword>
<keyword>method</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 Relationships" anchor="model">
<t>
The LINK and UNLINK methods are used to manage relationships
between resources. Those relationships are defined using the Link
model established in Section 3 of <xref target="RFC5988" />. For
every individual link, the context IRI, link relation type, target
IRI, and optional collection of target attributes MUST be considered;
that is, for any effective request URI, there can exist at most one Link
relationship between any context and target IRI pairing with any given
combination of link relation type and target attributes.
</t>
<t>
Within LINK and UNLINK requests, a <xref target="RFC5988"/> Link
header field is used to describe a Link relationship to be
managed. Any single LINK or UNLINK request MAY contain multiple Link
header fields, each of which describes a separate relationship between
a context IRI and target IRI. When a LINK request contains multiple
Link header fields, the server MUST create all of the specified relationships
or not create any of them. Likewise, when an UNLINK request contains
multiple Link header fields, the server MUST either remove all the
specified relationship or not remove any of them.
</t>
<t>
The target and context IRIs of a Link relationship are determined
following the requirements specified in Sections 5.1 and 5.2 of
<xref target="RFC5988"/>.
</t>
<t>
When determining whether or not a relationship already exists between
a context IRI and target IRI, implementations will need to compare the
given IRIs with other, previously established relationships. To do so,
the implementation MUST first resolve the IRIs as required by
<xref target="RFC5988" /> and then compare on a case-sensitive,
character-by-character basis. For instance, the IRIs
"http://example.org/foo" and "http://example.org/Foo" MUST NOT be
considered to be equivalent.
</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 the relationships being established. A payload
within a LINK request has no defined semantics.
</t>
<t>
LINK requests are idempotent but are not safe. Establishing a
relationship causes an inherent change to the state of the target
resource.
</t>
<t>
Any successful response (using a 2xx status code) to a LINK request
indicates that all of the Link relationships described in the request
have been established. No specific 2xx status code is required.
</t>
<t>
Responses to LINK requests SHOULD contain one Link header field
for each Link relationship established by the LINK request.
</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>
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>
</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 SHOULD contain one Link header field
for each Link relationship removed by the UNLINK request.
</t>
<t>
Any successful response (using a 2xx status code) to an UNLINK request
indicates that all of the Link relationships described in the request
have been removed. No specific 2xx status code is required.
</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>
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 established only under the
circumstances described by the conditional header field(s).
</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>Possible response:</preamble><artwork><![CDATA[
HTTP/1.1 202 Accepted
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>Possible response:</preamble><artwork><![CDATA[
HTTP/1.1 204 No Content
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>
<figure><preamble>Example 7: Using the Link anchor attribute to change the
context IRI (in this example, a link relationship is established between
the IRIs "acct:joe@example.org" and "acct:sally@example.org")</preamble>
<artwork><![CDATA[
LINK /my-resource HTTP/1.1
Host: example.org
Link: <acct:joe@example.org>; rel="follow"; anchor="acct:sally@example.org"
]]></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>
<section title="IANA Considerations">
<t>
IANA is requested to add the LINK and UNLINK methods to the
permanent registry at <http://www.iana.org/assignments/http-methods>
(see Section 8.1 of <xref target="I-D.ietf-httpbis-p2-semantics" />).
</t>
<texttable>
<ttcol>Method Name</ttcol>
<ttcol>Safe</ttcol>
<ttcol>Idempotent</ttcol>
<ttcol>Specification</ttcol>
<c>LINK</c>
<c>No</c>
<c>Yes</c>
<c><xref target="link"/></c>
<c>UNLINK</c>
<c>No</c>
<c>Yes</c>
<c><xref target="unlink"/></c>
</texttable>
</section>
</middle>
<back>
<references title="Normative References">
&rfc2119;
&rfc5988;
&part2;
&part4;
&part6;
</references>
<references title="Informational References">
&rfc2068;
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 05:22:33 |