Re: How much REST should your Web API get?

I know I am bit late to the party here, but I would like to contribute with
a small real life story about a RESTful API for mobile clients - an example
which in my opinion illustrates rather well that hyper media is useful for
mobile clients as well.

The setup is as follows:

   1. We (cBrain) develop software for governmental case file management.
   2. The software is installed on location on different customer sites.
   Each of the sites has their own installation of the server side REST API.
   3. We have a mobile iPad client that synchronizes selected case files to
   the iPad for off-line browsing.

Due to the way the central iPad app-store works this means that both our
clients and servers must deal with all possible combinations of different
versions of the software: a new client may have to deal with an old server,
just as well as an old client must work with a new server.

We decided to go "full monty" and stick as closely as possible to the REST
constraints - especially hyper media. This means our clients have one, and
only one, single entry point to the REST service - and that entry point
contains a service document with links/link-rels to all top level
resources. No hard coded URL structure on the client. The rest is classic
"follow your nose" links embedded in all resource representations.

Happy moment number one was this: a new, improved and more efficient,
synchronization mechanism was introduced without requiring a mandatory
upgrade of all clients.

We simply did what REST does best: introduce a new resource and add that to
the service document with a new link-rel. Now, old clients look for the old
link-rel and new clients look for the new link-rel. This does of course put
a maintenance burden on both clients and servers since they have to support
both ways of synchronizing for some time.

Happy moment number two was this: someone decides to include some third
party stuff that happens to look more a less like a case file - now the
clients should be able to synchronize and show both the original case files
and the new kind-of case files.

This too was easy using hyper media: the clients make no assumptions about
URLs so they really don't care how the URLs look - and thus the server is
free to embed any information it wants in the URL (in this case identifying
what kind of case file it points to). When the client asks for the list of
relevant case files it is then served a list of highly heterogeneous URLs,
but as long as any of these resources behaves as case file is expected to,
the client happily goes on without ever noticing that new types of case
files has been added.

So what am I trying to say here? Well, part of the earlier conversation
hinted that hyper media might be overkill for mobile clients. I just want
to illustrate the opposite: hyper media can be good for mobile clients :-)

The last happy moment also illustrates what (I think) was meant by "*A REST
API should never have “typed” resources that are significant to the client*"
in Roy's famous rant "REST APIs must be
hypertext-driven<http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven>".
Had the client known anything about the internal type behind the facade
then it would have failed when we introduced multiple types behind the
facade.

/Jørn