You just have to keep in mind the goal of REST: self navigation. Given a known document, it should be possible to automatically navigate the graph of related do

You just have to keep in mind the goal of REST: self navigation. Given a known document, it should be possible to automatically navigate the graph of related documents. REST, technically, is a poor choice for an API. REST assumes, at least in my opinion, a human driver on the consumption side. A rendered page is for a human. REST coalesces HTTP. HTTP came first. To get anything useful from an API requires as much context as deriving meaning from an HTML document. REST, by itself, does not try to give a semantic meaning to the data. An API does. So take the useful and leave the useless. If you want to extend JSON to link, fine. Just make sure you document your new type. If you want to use just the noun + verb paradigm, go ahead. Please be consistent. Please document your assumptions.