-
-
Notifications
You must be signed in to change notification settings - Fork 287
Hypermedia and APIs
Collecting feedback in issue #287
[DISCLAIMER: This is @handrews's view, and subject to debate and revision. It will probably move to the web site as it gains acceptance. If it gains acceptance]
JSON Hyper-Schema provides mechanisms to describe links, but assumes a thorough understanding of hypermedia concepts on the part of the hyper-schema authors and consumers in order to use it correctly in an API. The knowledge necessary to fully understand how to make use of hypermedia is scattered across many RFCs, some less obvious than others. This page gathers the key points into a guide to understanding how to write and use JSON Hyper-Schema Link Description Objects (LDOs).
As defined in RFC 5988, a link is "a link is a typed connection between two resources that are identified by Internationalised Resource Identifiers." Links are directional, pointing from a context resource to a target resource. The link's relation IRI identifies the link's type. (Note: Since Hyper-Schema does not currently address IRIs, this document will primarily discuss URIs, but the principles remain the same.)
These three IRIs/URIs (context, target, and relation) are the minimal elements needed to define a link, with the context most often implicitly defined by the position of the link within a document. Additionally, a link may include several other kinds of information, including presentation metadata, target hints, an explicit context URI, or a description of additional data that can be used with the link.
Presentation metadata is more or less irrelevant to link semantics. Fields such as "title" may clarify the link's semantics for humans, but are not expected to be parsed or analyzed by automated systems.
Target hints are hints because only the target resource itself can provide authoritative information about its representation. Despite being non-authoritative, target hints are often useful shortcuts for content negotiation and other things that, in an HTTP system, might require a HEAD or OPTIONS request to be issued first. However, requests that depend on target hints may fail or produce an undexpected response at runtime.
There is an important and often-overlooked distinction between links (which express a relationship between two entities) and operations (the set of possible interactions that a client currently examining the context resource can have via the link with the target resource).
URI schemes that map to network protocols allow for remote operations. For a link whose URI scheme is http:// or https://, the possible operations correspond to the HTTP protocol methods.
Other URI schemes allow for local operations. The data: URI scheme is used to include a data string inline in another hypermedia format. The only operation you can do with such a URI is read its data.
Another confusion exists with resources (abstractions identified by a URI with which one may or may not be able to communicate) and endpoints (URLs to which a client can establish a connection in order to perform remote operations).
The concept of an endpoint is common to both RPC and REST, while resources are more or less specific to REST. Technically, there is a resource at an RPC endpoint, because everything is a resource. But unlike in REST, you do not interact with it through is own representation. It is simply a conduit through which you execute the calls.
In either system, you need endpoints in order to perform remote operations, whether they are RESTful interactions with the resource at that endpoint or not.
Note that even if a URI is a URL indicating a protocol, or has a URI scheme that defines one or more local operations, there is no guarantee that it is suitable for use with those operations or that protocol. For instance, some link target URIs are intended only as identifiers, and may not be dereferenceable even if they appear to be.
This sort of restriction should be conveyed by the link's semantics. We will go into more detail shortly, but as an example, the "profile" link relation specifies that its target URI is an identifier only, and SHOULD NOT automatically be dereferenced even if it appears to be a URL based on its scheme.
It's worth taking a slight digression here into API description systems such as OpenAPI, RAML, etc. While hypermedia formats work in terms of links and resources, API description systems focus on operations and endpoints, including the various possible responses to each operation.
A single Hyper-Schema corresponds to a single set of resources defined by the possible expansions of its "self" link's URI Template.
An API description document describes all possible endpoints and operations of a finite set of resource sets. This set of sets is generally closed and managed by some authority that controls the API. Most API description systems focus primarily or entirely on HTTP, with syntax that will not work with any other protocol.
While a Hyper-Schema document, or set of documents connected by "$ref"s, can be assembled to correspond to an API's set of resource sets, and therefore look somewhat like an API description document, there is no such grouping inherent in the Hyper-Schema format. As a general-purpose media type, a Hyper-Schema document may be used outside of the sort of closed system that we normally think of as an API.
Hypermedia in general is intended for open-ended, dynamic sets of documents, including conceptually open-ended dynamic APIs. Such an API would not pre-define its boundaries, so a given client may only ever see the parts that it needs, without concern for what else may or may not be included.
In contrast, API description systems always correspond to a well-defined API (set of resource sets), and therefore can also describe information such as authentication/authorization, which is an orthogonal concern to simply adding hypermedia controls to JSON.
Notably, the focus that API description systems put on operations allows them to describe link usage that does not correspond to standards such as RFC 7231: HTTP Semantics. Hypermedia formats do not explicilty describe operations, and therefore have no such capability.
The biggest question in hypermedia systems, particularly truly RESTful APIs (that meet all required constraints from Fielding's dissertation), is how an automated client is supposed to understand what it can do.
A truly RESTful API should be usable by a generic client library, or agent, that understands the URI schemes, media types, protocols, and standardized link relations found within the API. Such an agent is to REST APIs as web browsers are to human-oriented hypermedia, a.k.a. the World Wide Web.