In July of 2022, the Internet Engineering Task Force, better known as the IETF, codified a new media type for link sets as part of their ongoing efforts to expand the IETF standards. This proposed standard, formerly called Linkset: Media Types and a Link Relation Type for Link Sets RFC 9264, has wide-reaching implications for APIs. The Linkset standard is co-authored by Erik Wilde and Herbert Van de Sompel and is an output of the Building Blocks for HTTP APIs working group.

Today, we’re going to do a deep dive into this standard. We’ll look at the reasoning behind its development, dig into the motivation behind issuing it as a standard and look at some potential use cases.

What Is the Building Blocks for HTTP APIs Working Group?

Before we get into the standard, we should quickly discuss who the working group behind it is. In essence, the Building Blocks for HTTP APIs Working Group is designed to cover HTTP uses outside the traditional use case served by HTTP standards — that is, use cases for HTTP that facilitate machine-to-maching communication through HTTP APIs. This realm of interaction often has a very different set of needs and circumstances than traditional HTTP standards serve, requiring a different mindset and approach.

The working group was thus created to focus on three specific outputs, which are documented in their charter:

• Specifications for HTTP extensions that relate to HTTP APIs (typically, new HTTP header and/or trailer fields)
• Specifications for new message body formats, or conventions for their use in HTTP APIs (e.g., patterns of JSON objects)
• Best practices and other documentation for HTTP API designers, consumers, implementers, operators, etc.

Why The Linkset Standard?

With the backdrop of the working group understood, we can begin to look at the reasons the standard was needed. When considering the current methodology of linkset handling, there are several situations in which the previous standards were deficient.

First and foremost, the new linkset solution provides for a more streamlined method of linking relevant resources when those resources are from a third party. The idea of hypermedia — the ability to provide media that is linked to information — drives the modern web. In many implementations, however, complex code was needed when the additional contextual information was provided by a third party, not by the server or the resource itself. To get around this, the IETF working group built a system in which two separate media types and a link relation type are created, providing additional contextual links and relating those links to the resource and the server serving the link through a relation type.

Secondly, the standard was designed to meet a challenge that was occurring with writing to the HTTP “Link” header field. This field was widely used as a solution to providing additional linked information, but in certain circumstances, writing to this field was made difficult due to insufficient access to the final linked information or a lack in capability or means to write to the field itself. This rendered the header field useless in certain use cases. The common solution to this issue is to provide links through a standalone document. While this solves the problem somewhat, it does create issues with discoverability. The standard implements a typed link to help recognize and navigate these documents, thereby making them discoverable.

Finally, the standard document notes a third use case in the form of large numbers of links. In the case of dynamic responses, where the response size is almost impossible to predict without making the query, the possible size of the response field can grow too large for consumption. While this can be worked around by creating an upper bound for size, this upper bound is essentially random, as the upper bound cannot be adequately estimated. The standard considers this also solved through support and discoverability of the standalone documents, as the size can be managed by making those links separate from the actual response to the HTTP “Link” header, in essence, sidestepping the size limitation altogether.

How Does it Work?

This Linkset definition works through several systems.

It defines two document formats as a standard for conveying sets of links. The standard adopts the “Web Linked” section of the RFC8288 model, and sets forth the expectation that these standards should have “link context,” a “link relation type,” a “link target,” and optional “target attributes” in order to standardize the link itself.

The two formats created to facilitate this type of relational data is the “application/linkset” and “application/linkset+json” formats. “application/linkset” is, in essence, nearly the same as the HTTP “Link” header field, but it differs in the supported separator form, allowing newline characters in addition to spaces and horizontal tabs for improved human readability. “application/linkset+json,” predictably, is a JSON implementation of the core “application/linkset” approach.

Additionally, the “profile” media type parameter was created to express constraints or conventions that apply to the link set document. This allows for the rules to be expressed to the end user when engaging with the specific linkset document, serving as a sort of encoding expression to help in the process of understanding and parsing.

Finally, the standard introduced the “linkset” relation type, a key functionality to this entire endeavor. In essence, the linkset relation type allows a link to express that it’s linking specifically to a linkset, which, in conjunction with the other systems within the specification, allows for the functionality intended by the working group.

Example of Linkset Typing

So, what does Linkset look like in practice? Section 7 within the RFC demonstrates some examples of using Linkset. These samples from the RFC below showcase a set of links provided as “application/linkset” and “application/linkset+json” documents.

First, here is a client issuing a call to a resource at “https://example.org/links/resource1”.

GET /links/resource1 HTTP/1.1
Host: example.org

And here is the response below. As you can see, the response specifies that the media type is “application/linkset” and a set of links is represented in the response body.

HTTP/1.1 200 OK
Date: Mon, 12 Aug 2019 10:35:51 GMT
Server: Apache-Coyote/1.1
Content-Length: 1023
Content-Type: application/linkset
Link: <https://example.org/links/resource1>
      ; rel="alternate"
      ; type="application/linkset+json"

<https://authors.example.net/johndoe>
   ; rel="author"
   ; type="application/rdf+xml"
   ; anchor="https://example.org/resource1",
<https://example.org/resource1?version=3>
   ; rel="latest-version"
   ; type="text/html"
   ; anchor="https://example.org/resource1",
<https://example.org/resource1?version=2>
   ; rel="predecessor-version"
   ; type="text/html"
   ; anchor="https://example.org/resource1?version=3",
<https://example.org/resource1?version=1>
   ; rel="predecessor-version"
   ; type="text/html"
   ; anchor="https://example.org/resource1?version=2",
<https://example.org/resource1?version=1>
   ; rel="memento"
   ; type="text/html"
   ; datetime="Thu, 13 Jun 2019 09:34:33 GMT"
   ; anchor="https://example.org/resource1",
<https://example.org/resource1?version=2>
   ; rel="memento"
   ; type="text/html"
   ; datetime="Sun, 21 Jul 2019 12:22:04 GMT"
   ; anchor="https://example.org/resource1",
<https://authors.example.net/alice>
   ; rel="author"
   ; anchor="https://example.org/resource1#comment=1"

In the response above, the “Link” field denotes that there is an alternative format held at “application/linkset+json”. So, let’s call that next to see what the JSON would look like. Here is the request:

GET links/resource1 HTTP/1.1
Host: example.org
Accept: application/linkset+json

The resultant output is as follows:

HTTP/1.1 200 OK
Date: Mon, 12 Aug 2019 10:46:22 GMT
Server: Apache-Coyote/1.1
Content-Type: application/linkset+json
Link: <https://example.org/links/resource1>
      ; rel="alternate"
      ; type="application/linkset"
Content-Length: 1246

{ "linkset":
  [
    { "anchor": "https://example.org/resource1",
      "author": [
        { "href": "https://authors.example.net/johndoe",
          "type": "application/rdf+xml"
        }
      ],
      "memento": [
        { "href": "https://example.org/resource1?version=1",
          "type": "text/html",
          "datetime": "Thu, 13 Jun 2019 09:34:33 GMT"
        },
        { "href": "https://example.org/resource1?version=2",
          "type": "text/html",
          "datetime": "Sun, 21 Jul 2019 12:22:04 GMT"
        }
      ],
      "latest-version": [
        { "href": "https://example.org/resource1?version=3",
          "type": "text/html"
        }
      ]
    },
    { "anchor": "https://example.org/resource1?version=3",
      "predecessor-version": [
        { "href": "https://example.org/resource1?version=2",
          "type": "text/html"
        }
      ]
    },
    { "anchor": "https://example.org/resource1?version=2",
      "predecessor-version": [
        { "href": "https://example.org/resource1?version=1",
          "type": "text/html"
        }
      ]
    },
    { "anchor": "https://example.org/resource1#comment=1",
      "author": [
        { "href": "https://authors.example.net/alice"}
      ]
    }
  ]
}

With this simple request pattern, we have ascertained not only the linked resource, but the linkset, which provides ample links to other relational pieces of data, thereby opening up additional context and functionality.

Conclusion

The Linkset specification is a novel implementation of a linkset approach that unlocks additional capability. Providing additional relational links is just the start, as additional implementations and iterations can result in some unique use cases and applications across multiple media types.

What do you think of the new Linkset specification? Let us know in the comments below!