There has been a plethora of commentary on the need to include “links” in resource representations. In fact, Subbu has recently posted this and this on the very subject. It’s obvious that the “web” works because of links that point to other resources.
However, the web would not work if representations (HTML pages being the most popular representation) had links that went nowhere and basically 404s were returned. For links to be meaningful (really) they need to “link” to actual resources that return legitimate representations. These links should be part of a general process/application flow for that (or set of) resource(s) and have some semantics to them.
I find the primary challenge with having representations return links is that most developers I know are not building new systems, rather they are introducing resources into a system that was not originally resource-oriented. Having representations with links would mean exposing existing services as resources (and exposing it correctly). This requires time and effort, time and effort many dev teams don’t have.
Because of the above challenge, documenting the resources a system exposes seems paramount. I don’t have a strong feeling as to “how” these resources hould be documented. But documented they should be.