It seems to me that most, if not all, examples of REST begins like this: "Assume we have some service X with different kinds of resources R1, R2, ..., Rn". The better example will not go into details about URL structures and some will even show how hyper media can be used to link the resources together.
But something is fundamentally wrong with this approach; it has the underlying assumption that service X is the one and only service on the whole Internet that implements resources R1-Rn - and that assumption makes it difficult for the readers to actually understand the core drivers of REST as being a style for globally distributed systems. It plain and simply misses the fact that many different servers, from different independent organizations, may implement those resources R1-Rn.
This approach fails to illustrate the problem of keeping many different client and servers in sync. And it fails to illustrate why URLs and especially hyper media are such good things. Why? Because singe service URLs have static URL templates - and using hyper media on the client side seems like totally overkill when the client might as well use the templates directly.
So allow me to give a slightly different example. It begins like this: "Assume we have resources R1, R2, ..., Rn hosted by different independent services". Now we can start talking about the benefits of hyper media since there would be no predefined URL templates to look at.
So how would such an example look? Let me try to present one:
In a (distributed) teaching application we have resources that represent Schools, Classes, Teachers and Students. These resources are hosted on a "per province" basis - meaning that each province in the country has its own servers that hosts one or more schools belonging to the province. These servers are implemented independently and by different vendors and there is no central specification of any URL structures.
Now, given the URL to a single teacher we can GET a JSON representation of her including references to the classes she teaches:
Name: "Louise Nelson",
As can be seen from the concrete URL examples there is no URL template in the world that a client of this system can depend on. Now it makes much more sense to use hyper media - how else would the client know how to get more information about the classes Louise Nelson teaches?
So, do you agree with this? Are existing examples really like I claim or have I overlooked something? Should we, as the community of experienced REST scholars, create new and better examples?