Using Proper "rel" Values in JSON-Hyper Schema

What are Proper "rel" (relation) Values?

The relationship of a resource to it's links is an important consideration. It serves as not only a way to semantically indicate the importance of the transition from one resource to another. It can serve as a way to organize application state. Machines can learn to follow this kind of organization: much like the Google bot does. We can design our own set of relations, ones which well define the types of relationships that exists in APIs and on the internet. Or, perhaps, we can leverage existing relations. Leveraging exisiting relations is exactly what the JSON-Hyper Schema standard has done, and for good reason. Let's examine.

Relation Standards are Present.

It would be nice to use a standardized set of relations. This would make reusability of any code you write, to parse or display relations, easier. Fortunately, I am not the first to think of this concern. JSON Hyper Schema references a set of relations that can be used. Those relations are maintained by IANA (See http://json-schema.org/latest/json-schema-hypermedia.html#anchor40), which should point to this Registry: http://www.iana.org/assignments/link-relations/link-relations.xhtml. These sets of link relation definitions give a broad coverage of the set of relationships used in most over-the-internet transactions.

There are many good resources for finding well defined link relations. Another good resource is for the user facing web, specifically. It coincides mostly with what IANA publishes in the aforementioned standard for link-relations. https://tools.ietf.org/html/rfc5988#section-6.2. So there is a lot of concesus about which relations are necessary. There are standards for adding new relations, when needed. For my purposes, the standard relations should suffice. However, JSON Hyper Schema defines few additional relations of it's own (http://json-schema.org/latest/json-schema-hypermedia.html#anchor27).

How I use Relations

I use relations to convey to a human being the meaning of the link traversals they might take. In my Hypermedia API, I provide links as a way to transform the state of the application. The user interface (UI) provides clues and guides a human being to when they should make a link traversal. For instance, when a user clicks the Logo on a website, the common conception is for the link traversal to go to the home page. Such is also true of any API, that a relation of "root" should go to the base API URI: "/api/v1.0". As such, JSON Hyper Schema adds the "root" relation to the standard relations: http://json-schema.org/latest/json-schema-hypermedia.html#anchor27. I use the API relations to convey meaning to a Client side javascript application, which makes choices based on relations.

The Client Application Makes Choices

A client application makes choices about whether to display a relation to a human, but also whether to perform relation actions itself: automatically. The more complete the client, and the more standard the relations defined, the more intelligent the client can be about making traversals automatically.

An example of an automatic traversal is when a preview relation is present, then an application might prefetch that preview, even before the human clicks the link, so that the resource preview loads faster. There can also be more complex actions, combinations of actions, and even inactions taken automatically by an application, based on relations and their standard defined meanings.

Thinking about Traversals

Using the right rel for a link in an API involves thinking hard about the nature of the relationship between the link's resource and the current resource context. For instance, you might want to design a resource which provides information about a bicycle, the whole bicycle. That resource could provide basic information about the bicycle, like the make model. Perhaps there are multiple version of the model: Trek Madone 1.1, Trek Madone 3.1, Trek Madone 4.1... To access this information you might provide several links from the basic info. Thos links go to a resource that provides the version info: such as the drivetrain components used, the wheelset, the handlebars, stem, seat, and seatpost used. This additional, version information is related to the make/model basic information. But how?

You need to think about how the traversal relates to the present resource. Let's look at the standard relations that we can use. Here are a few that might be applicable.

item	The target IRI points to a resource that is a member of the collection represented by the context IRI.
subsection	Refers to a resource serving as a subsection in a collection of resources.
related	Identifies a related resource.

Deciding which one fits best

Which one of these rel fits our intended traversal? related is easy to rule out, because item and subsection are more specific. related is very generic, and should be avoided unless no other relation can be used. rel === related, which seems duplicitous and not very meaningful. I would render a "related" link in a footer, or perhaps a collection of "related links," which would not be the center of focus I want to convey to users of my API.

Juxtaposing rels

"Subsection" is more suitable than "item," because a version of a Madone can't be said to be an item in a collection so much as it is a type of Madone. A collection of Trek Madones would be a set of actual instances of that bicycle. Think about how it's best to visualize the two. If I am comparing a collection of actual bicycles, then I need a lot of details, as an actual bicycle is a very detailed and specific thing: it can have scratches, part wear, and perhaps even specific history: Lance Armstrong's bike for instance. On the other hand, a subsection of a bicycle model will be more generic, and could be visualized in a very generic, stock, image of a typical Trek Madone 4.1. A subsection is more abstract of a concept, which encompasses a broader relationship. Think about it, and then make a choice.

Choosing a Relation Based on Usage

Consider how you would use the relation, and how your customer would. I would choose "subsection", based on how I would render a "subsection", versus a collection "item". I would render a "subsection" as a side by side comparison. I would render a collection of "items" as a grid of instances. A "subsection" can be optimized for comparison, because the level of detail to be considered is smaller. This visual consideration is vital to informing my choices. Perhaps I am more visual than you, or perhaps it is a visual world we live in. Consider your audience when designing rel values. The rel can be used by the customer's client software to choose visual layouts, or perhaps for someone blind, the audio cues would take into account the relations. Think about it.