Much like the Web’s HTML-based hyperlinks (links) and forms, REST APIs employ hypermedia within representations. A REST API response message’s body includes links to indicate the associations and actions that are available for a given resource, in a given state. Included along with other fields of a resource’s state representation, links convey the relationships between resources and offer clients a menu of resource-related actions, which are context-sensitive.
On the Web, users click on links to navigate a universe of interconnected resources. Despite the Web’s ever-increasing number of diverse resources, a few simple and uniformly structured HTML elements convey everything the browser needs to know in order to facilitate navigation. Similarly, REST API clients can programmatically navigate using a uniform link structure.
The following rules present WRML’s solution for representing the link and link relation structures.
The structure detailed in this rule represents a single link. Links should be included, along with fields, within resource state representations. A single link does not typically stand alone as a request or response message body’s content. However for completeness sake, the media type for the link structure is defined below:
# NOTE: the line breaks below are for the sake of visual clarity. application/wrml; format="http://api.formats.wrml.org/application/json"; schema="http://api.schemas.wrml.org/common/Link" ...