We've been working on our handling of links, and a lot of question have arisen.
There is a lot of confusion over how to represent links>.
The problem with that is that it's not immediately obvious to a program that this is a link (it could be a piece of text that just happens to be a URI), and even worse, this tells us nothing about what's on the other side of this link, or how we're related to it.
Another possibility is to have composite links, e.g.:
This is much more descriptive, although there is still a lot of uncertainty regarding the "proper" values for
There is in fact a registry of "legal" values for the rel attribute, but a quick look at it should convince you that it's not all that useful in a REST/JSON context.
It's become quite common now for JSON objects to include a links section, e.g.:
This makes it very clear, but it's also rather verbose.