Pattern Sections
Pattern: Link Element 
a.k.a. Network-Accessible Identifier, Address Representation, Hypermedia Control
Context
The context in which this pattern can be applied continues from that of the pattern Id Element:
A domain model consists of multiple related elements that have varying life cycles and semantics. The currently chosen decomposition of this model into remotely accessible API elements suggests that these related entities should be split up into several API abstractions. API consumers want to be able to follow the relationships and call additional API operations to satisfy their information and integration needs. Following a relationships, for instance, can define the next processing step or provide more detailed information.
The address where this next processing step can be invoked must be specified somewhere. Such pointers are required to implement the REST principle of Hypertext As The Engine of Application State (HATEOAS) and when supporting Pagination of query response results delivered by Retrieval Operations.
Problem
How can API endpoints and operations be referenced in request and response message payloads so that they can be called remotely?
Forces
The requirements here are the similar those for the sibling pattern Id Element, but more demanding in the remoting context of this pattern:
- Effort versus stability
- Readability for machines and humans
- Security (confidentiality)
Pattern forces are explained in depth in the book.
Solution
Include a special type of Id Element, a Link Element, to request or response messages. Let these Link Elements act as human- and machine-readable, network-accessible pointers to other endpoints and operations. Optionally, let additional Metadata Elements annotate and explain the nature of the relationship.
Sketch
A solution sketch for this pattern from pre-book times is:
Example
The Atlassian JIRA REST APIs have the notion of “remote issue links”. This API endpoint and operation for creating remote links includes URIs in requests and responses to POST requests. With a request body such as:
{
"object": {
"url":"http://www.mycompany.com/support?id=1",
"title":"Crazy customer support issue"
}
}the corresponding response is:
{
"self":"http://localhost:8090/jira/rest/api/latest/issue/TST-1/remotelink/100",
"id":100
}The self link can then be used to get more information
about the issue, etc.
Are you missing implementation hints? Our papers publications provide them (for selected patterns).
Consequences
The resolution of pattern forces and other consequences are discussed in our book.
Known Uses
Although REST level 3 and HATEOAS are mandatory constraints/principles according to R. Fielding who specified the REST style in Fielding (2000), a minority of today’s Web APIs are true Hypermedia APIs that use the concept. APIs that do use it include:
- Atlassian JIRA provides a dedicated API to deal with remote links to issues, the JIRA REST API for Remote Issue Links.
- APIs supporting cursor-based Pagination (see that pattern), including Facebook, GitHub, Google Calendar, YouTube (to name only a few)
- A Swiss software vendor specializing on the insurance industry
describes hypermedia controls mechanism in its internal REST API Design
Guidelines. Resource representations contain arrays of objects that have
attributes (a.k.a. fields) such as
href,rel,method, andtype. The level of detail can be specified by the consumer; an HTTP header calledhypermedia-controlwith the valuesnon,minimal, anddefaultis defined for that purpose.
Spring HATEOAS supports the pattern, for instance with the Entity Links concept and interface. The Hypertext Application Language (HAL) suggest a syntax for it. The Hydra project centers on the vision of hypermedia-driven Web APIs using JSON-LD (Lanthaler (2013)).
RESTBucks is the RESTful design of a canonical integration and messaging scenario.
More Information
Related Patterns
Id Element is a related pattern, also providing uniqueness of (local) references to API elements. Both patterns are special types of Data Elements. However, Id Elements do not contain network-accessible and therefore globally unique addresses (unlike Link Elements). Id Elements typically also do not contain semantic type information as we suggest to include in Link Elements. Both Link Elements and Id Elements can be accompanied by metadata, but also may qualify as metadata themselves.
Link Elements can be used to realize Pagination and hypermedia-driven State Transition Operations. Either locally valid Id Elements or full, globally valid Link Elements might be returned by State Creation Operations.
A Link Element may be represented with an Atomic Parameter structure (as it refines this basic representation pattern). They are particularly useful when realizing distributed business processes as an orchestrated set of State Transition Operations exposed by one or more Processing Resources.
Linked Service in Daigneau (2011) captures a related concept, the target of the Link Element. Pautasso, Ivanchikj, and Schreier (2016) feature related patterns for RESTful integration such as Client-side Navigation following Hyperlinks, Long Running Request and Resource Collection Traversal.
Other Sources
See an online REST Cookbook for additional design concerns.
Chapter 5 in the RESTful Web Services Cookbook by S. Allamaraju (Allamaraju (2010)) presents eight recipes for “Web Linking”. For instance, Section 5.4 discusses how to assign link relation types. Chapter 4 in the same book gives advice on how to design URIs. Also see Chapter 12 of Sturgeon (2016) for Link Elements in RESTful HTTP.
The ALPS specification also deals with link representations (recommended for instance in M. Amundsen’s books/articles/interviews), just like RFC 6906 (drafted by E. Wilde). There is another draft RFC called JSON Hypertext Application Language that suggests a link relation media type.
“Designing & Implementing Hypermedia APIs”, a QCon presentation by M. Amundsen is a good starting point for investigation. Many examples can be found in the GitHub repository of the API Academy.
Libraries and notations that implement the concept include HAL, Hydra, JSON-LD, Collection+JSON, and Siren; see this presentation and this blog post.