Define a mechanism for custom link relationships

Problem/Motivation

We now have a way for Entities to define link relationships they support; the most notable is canonical, but it can define any other IANA-defined relationship. We then automatically add those relationships in various places, and intend to do so for REST plugins on Entity at least.

However, that only works for the IANA-standardized relationships. In reality, any serious RESTful API is going to need to define custom relationships. It is not correct however to simply throw additional link names around willy nilly. That leads to collisions and confusion. Rather, they need to be namespaced. Namespaces are expected to be a URI. So you'd end up with something like this:

http://drupal.org/rels/owner = http://drupal.org/user/5

(for a link that points to a node owner from a node resource)

That's ugly, of course. Instead, the common way to do that is with a curie alias. (I'm sure Lin Clark can correct my overly simplistic explanation here.) Essentially, you shorten the namespace to a simple string and provide a lookup for it that points to human-friendly documentation. So:

drupal:owner = http://drupal.org/user/5 
curies = [
http://drupal.org/rels/{rel}, name="drupal"
]

And then http://drupal.org/rels/owner would contain documentation on what "owner" means.

Not only do we have no defined namespace, we also have no way for any modules to define links within that namespace. If people want to build out well-behaved REST-style APIs on Drupal, they're going to need a way to properly define and use extra link relationships.

Proposed resolution

What we need is a way to let modules:

1) Define new link relationships
2) Associate a link to a given REST resource (which could be an entity or not)
3) Add additional links to a resource
4) Automate a way to expose the aforementioned documentation/curie.

How we do that is an open question. In Drupal 7 the knee-jerk response would have been "info hook!", but that's not a good approach in Drupal 8. The natural next knee-jerk response is "plugins!", but I'm not convinced that's right either. (It may be, though.) We should figure this out, and then implement it.

Remaining tasks

Figure out an API here, then implement it..

User interface changes

Likely none.

API changes

This should be possible with no changes to existing APIs, just additional functionality that is currently sorely missing.

Related Issues

#1925618: Ensure Drupal's web services are self-documenting: Swagger support OR rest_api_doc to Drupal core as an experimental module?
#2019123: Use the same canonical URI paths as for HTML routes