Re: How much REST should your Web API get?

It seems to me that the biggest difference between "Web API" and "REST" is
a matter of perspective: Web APIs talk about THE server and all its clients
whereas REST talk about MANY servers and multiple clients.

This difference in perspective influences many decisions and view points:

- Web API: A single server need not coordinate with other servers, owned by
other authorities, when it changes its representations - it only needs to
inform its clients about it.

- REST: all servers must adhere to a common set of well defined, stable,
specifications (media types) otherwise it would be impossible for the
clients to interact with all the different servers.

In an ecosystem with one single server and custom build clients (Twitter
clients for instance) there really is no need for media types/uniform
interface: the client can safely assume that the server is going to return
JSON in one specific flavor each and every time the client makes a request
to it. Neither is hyper media of much relevance since it is quite safe to
assume that the server won't change its URL structure.

In an ecosystem of global scale with many servers it is quite the opposite:
different servers are not implemented by the same development teams and
thus, without a mechanism like media types, the clients really wouldn't
have any way of knowing what kind of information a resource representation
might contain. Neither can the clients make any assumptions about URL
structures across disparate server implementations.

It is this difference in perspective that makes it hard for developers to
understand the benefits of REST: if all they want to implement is a new
one-off snowflake service with dedicated clients then its difficult to
argue for some of the uniform interface constraints.

Relaxing on the constraints can probably be fine when the goal is a one-off
non-REST service - and this is probably often the case: who says Twitter is
interested in being reduced to a commodity service that we can find all
over the web? Had Twitter/Facebook/others decided to define their interface
in terms of shared media types then they would have reduced them selves to
a commodity from the very beginning. This, I believe, is one of the reasons
that we don't see many domain specific media types in the wild.

/Jørn






On Fri, May 3, 2013 at 9:57 PM, Jørn Wildt <[email protected]> wrote:

> 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
>