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
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.
"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.