Posted on by & filed under Content - Highlights and Reviews, Programming & Development.

REST is now the most common approach used for designing Web APIs. A well-designed REST API is based upon media types that define the message formats used in client-server exchanges. See REST APIs in the REST API Design Rulebook for more on this topic. A media type will document both the structure of a valid message and the hypermedia “controls” used to interact with resources.

Examples of controls are forms or typed links. The HTML media type defines several controls, including:

  • The img and a elements use links for transclusion and navigation
  • The form elements are used to construct requests to a server

Typed links are the most common form of control and provide the means for clients to traverse the functionality exposed by an API. When we are designing a new API, it’s useful to draw on existing patterns for designing links. It turns out that there is both a common conceptual framework that we can use, as well as an existing registry of link types.

A Conceptual Link Framework

Both HTML and Atom include a generic link element. For more on Atom, read Chapter 7.6: Atom Everywhere in Rest in Practice. In HTML, this is most commonly used to reference stylesheets:

Atom uses the atom:link element in a number of ways, for example, to publish the permalink to a blog post and the URI used to edit it:

The common aspects of these elements have been standardized as part of RFC 5988 (Request for Comments), which describes a conceptual framework for defining links in media types. This is exactly what we need for creating RESTful APIs.

RFC 5988 describes a number of key aspects of a link:

  • The Context URI — the resource to which the link applies, such as a specific Atom feed entry
  • The Target URI — the resource that is being referenced in the link, such as a stylesheet
  • The Link Relation — the type of the link, such as “edit” or “stylesheet” in the above examples

Optionally, there may be some standard Target Attributes that describe an aspect of the destination resource, like its title or expected media type (text/css).

But the RFC doesn’t define how links should be expressed, just its properties. The HTML and Atom examples show one way to capture that information in an XML format, while a potential JSON encoding might be:

Our media type documentation needs to define how a link will be formatted and, most importantly, what types of links a client might encounter. Client behavior is driven through discovering and following typed links.

Media types that use RFC 5988 style links are easily extended: all we need to do is define new types of link relations.

The IANA Link Registry

We may also be able to re-use existing link types. The IANA (Internet Assigned Numbers Authority) maintains a central registry for common link relations. There are a wide range of relations including:

  • A bookmark providing a permalink
  • A describes relation that asserts that one resource provides a description of another
  • An edit relation refers to a resource that can be used to edit the content of the context URI
  • Navigation relationships (previous, first, last, next) for moving within a list of resources

The registry is an excellent point of reference, either for inclusion in a custom media-type or as a source of new relations for an existing type. New types can be added to the registry, and it’s also possible to use a URI as an identifier for a link type, rather than a short name.

Instrumenting Existing APIs

Handily, RFC 5988 also defines a way to publish links via the Link HTTP header. This has a number of advantages:

  • Links can be published without changing current formats or clients, making it possible to make existing APIs more RESTful
  • Links can be used by clients without the need to parse and understand specific media types, allowing for some generic client interactions
  • Where a resource exposes data in multiple formats, it provides a consistent location for exposing the links that are common to all representations

The “edit” link from the earlier Atom example could be included in an HTTP header as:

Similarly, paging links could be exposed like this:

An API could also link to both the license associated with the data it returns and its terms of use:

Summing Up

Typed links are a core feature of any RESTful API. They provide the means for clients to traverse the functionality exposed by the API. By building on a common conceptual framework, and an existing registry of link relations, we can take advantage of existing experience and design patterns when designing new APIs.

Where we have limited freedom to add links to existing media types, we can still make those APIs more RESTful by exposing links at the HTTP protocol level.

For more details about REST, see the ebooks referenced below.

Safari Books Online has the content you need

REST continues to gain momentum as the best method for building web services, leaving many web architects to consider whether and how to include this approach in their SOA and SOAP-dominated world. Rest in Practice offers a down-to-earth explanation of REST, with techniques and examples that show you how to design and implement integration solutions using the REST architectural style.
The basic rules of REST APIs – “many nouns, few verbs, stick with HTTP” – seem easy, but that simplicity and power require discipline to work smoothly. REST API Design Rulebook provides the next steps for implementing complex REST projects on simple and extensible foundations.
SOA with REST: Principles, Patterns & Constraints for Building Enterprise Solutions with REST is the first comprehensive tutorial and reference for designing and building RESTful services as part of service-oriented solutions and in conjunction with service-oriented architecture (SOA). This book demonstrates that REST is not only a suitable medium for building truly service-oriented solutions, but also that the service-oriented architectural model is a necessary foundation for REST technology architectures to realize their full business potential.

About the author

Leigh Dodds is a freelance consultant specializing in Linked Data, Open Data and API development. Passionate about the web, open standards, and open source he enjoys exploring how to apply new technologies to create interesting products. He’s also quite fond of gaming, Lego, Minecraft and a good beer. You can reach Leigh on
Github: or on Twitter: @ldodds.

Tags: APIs, IANA, Links, REST, RESTful, RESTful API, RFC 5988,

Comments are closed.