Teaching REST - the missing link

"Jorn Wildt" <[email protected]>
Newsgroups gmane.comp.web.services.rest
Message-ID <[email protected]>
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",
   Classes:
   [
     {
       Name: "Science",
       Self: "http://province-a.edu/moobar/classes/98x-yy"
     },
     {
       Name: "History",
       Self: "http://another-province.edu/~his/classes?cid=123"
     }
   ]
}

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?

Thanks, Jørn
lmpx.com only provides a reader for public news (NNTP) servers. It is not affiliated with the servers or forums shown here and is not responsible for the content of articles, which is written by their respective authors.