Linkset: A Link Relation Type for Link Sets

A resource typically conveys typed Web Links as an inherent part of the resource's representation , for example, using the <link> element for HTML representations or the "Link" header in HTTP response headers for representations of any media type. Cases exist in which providing links in a by value manner is impractical or impossible. In these cases, an approach to provide links by reference is desired. This specification defines the "linkset" relation type that allows doing so.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 .

...

Cases exist in which a resource other than the responding resource is better placed to provide web links. That other resource is hosted by a link server that may be managed by the same custodian as the responding resource or by a third party. In order for the responding server to provide up-to-date links about its resource, it needs to obtain them from the link server, and embed them in the resource's representation prior to responding to a client. Doing so increases latency, which may be unnecessary if a client is not intent on consuming links. Providing links by reference, instead of by value, removes this additional latency by avoiding server-to-server communication required to obtain links.

When conveying links in the HTTP "Link" header, cases exist in which the size of the HTTP response header becomes unpredictable. This is, for example, the case when links are determined dynamically dependent on a range of contextual factors. It is possible to statically configure a web server to correctly handle large HTTP response headers by specifying an upper boundary for their size. But, when the number of links and the amount of bytes required for each is unpredictable, estimating a reliable upper boundary is challenging. While HTTP RFC 2616 defines error codes related to excess communication by the user agent ("413 Request Entity Too Large" and "414 Request-URI Too Long"), no error codes are defined to indicate that a response header exceeds the upper boundary that can be handled by the server. As a result, applications take counter measures aimed at controlling the size of the HTTP "Link" header, for example, by limiting the links they provide to those with select relation types, thereby limiting the value of the HTTP "Link" header to clients. Providing links by reference, instead of by value, overcomes challenges related to the unpredictable nature of the extent of HTTP "Link" headers.

The "linkset" relation type can be used by a responding resource to refer to another resource that provides a set of links. Typically the Context IRI of these links is the URI of the responding resource but links with other Context IRIs MAY be provided. The media type of the link set that is accessible via the Target IRI of a link with the "linkset" relation type is not constrained but the representation of the link set MUST allow a user-agent to unambiguously determine the Context IRI of each provided link. More than one link with a "linkset" relation type MAY be provided. Multiple such links can refer to the same set of links expressed using different representations or to different link sets. The use of a link with the "linkset" relation type does not preclude the provision of links with other relation types.

shows a user agent issuing an HTTP head request against resource http://example.org/resource1.

Sections and exemplify possible responses to the HTTP request of that include the provision of a link with the "linkset" relation type, as well as a user-agent following those links to retrieve a link set.

shows the response to the HEAD request of . The response contains a "Link" header with a link that uses the "linkset" relation type. It indicates that links are provided by another resource http://example.com/links/http://example.org/resource, which has media type application/link-format . Using this media type, links are serialized in the same manner as the payload of the "Link" header, which lowers the barrier for user-agents that are already able to consume HTTP links.

; rel="linkset" ; type="application/link-format" Content-Length: 5214 Content-Type: text/html;charset=utf-8 Connection: close ]]> shows the user agent issuing an HTTP GET request against the Target IRI of the link with the "linkset" relation type shown in .

shows response to the HTTP GET request of . As can be seen from this example, in order to support an unambiguous determination of the Context IRI of each link, an approach is taken whereby: The Context IRI is the URI in the "anchor" attribute, when provided. When no anchor parameter is provided, the Context IRI is provided by a unique link in the link set that has the "about" relation type and the URI of the link set resource as the value of the "anchor" attribute. The Target IRI of that link is the Context IRI of all links in the link set that don't have an "anchor" attribute.

; rel="about" ; anchor="http://example.com/links/http://example.org/resource1", ; rel="author" ; type="application/rdf+xml", ; rel="author" ; type="application/rdf+xml", ; rel="item" ; type="application/pdf", ; rel="item" ; type="text/html", ; rel="related" ; type="application/pdf" ; anchor="http://example.org/resource1/items/AF48EF.pdf", ... ]]>

In this example, the response to is the same as but the content of the "type" attribute is application/hal+json instead of application/link-format. Similarly, the user-agent's follow-up request is the same as but using application/hal+json in the "Accept" HTTP request header instead of application/link-format. exemplifies a response to that follow-up HTTP GET request issued against the link set resource.

The link relation type below has been registered by IANA per Section 6.2.1 of RFC 5988 :

Relation Name: linkset Description: The Target IRI of a link with the "linkset" relation type provides a set of links. Reference: [[ This document ]]

...