Re: [Jersey] Jersey's (experimental) approach to support hypermedia constraint

From: Jan Algermissen <>
Date: Wed, 10 Feb 2010 22:48:33 +0100

On Feb 10, 2010, at 10:03 PM, Marc Hadley wrote:

> On Feb 10, 2010, at 3:55 PM, Jan Algermissen wrote:
>> P.S. As radical as this might sound at first the consequences are actually far less dramatic but I do not want to clutter up this thread with those issues.
> I'm struggling to imagine what kind of specialized client program I could write that can't depend on *anything* from the server. Sure I could write a generic browser but how do I write a program that orders a widget without human intervention if I can't even rely on the media type I'm going to get back ?

Yes, I am glad you pick upon that one. I have been struggling with it for months. The problem is that on the one hand machine clients (except for bots) have their own state machine and on the other hand REST clients are driven by the state machine of the Web application. It is as if you'd create a GUI application that follows its own flow but is driven by the GUI user at the same time.

Browsers are different because they simply convert the application state they receive into a human accessable GUI.

REST style architectures guarantee a kind of decoupling between client and server that is amazing. A server developer really does not have to wory about the clients in any way. No need to bring development teams into a room to discuss what clients might be affected by what change. Just change the server and no harm will be done. If we sacrifice this decoupling achieved by REST because we *think* machine clients need to make such assumptions nothing is gained by REST. In fact, I'd say it would be harmful in the long run (because it is so easy to not document the assumptions made - there is no IDL to help us).

Here is my take on it in short:

- we need notions of service types (e.g. AtomPub) because without
  such notions we cannot develop clients in the absence of service

- what is a service type? In my opinion a service type is constituted
  by the set of media types it uses.[1]

- given this set, a client dveloper can implement a client because
  knowing the set of media types enables the developer to provide handlers
  for the possible responses.

- knowing the set of media types also tells me a lot about the
  possible media types for a given request because I can expect
  a server to send some sort of set-oriented media type (Atom feed,
  RSS) for collections.
  (If a server says <app:collection href="/feeds/1"> and sends
  an audio file for GET /feeds/1 then I'd sonsider that a
  broken server).

- Because the service type is the set of media types, a client
  can IMHO rely on the server not to stop supporting some
  media type of the set

What I found most interesting is that REST leads to a very clear separation of things that a service can guarantee to be stable over time and those things that it cannot guarantee to be stable. REST encourages developers to split the application into addressable states provided by resources and requires that the semantics of these resource is stable over time[2]. It actually also encourages the servers to maintain these states 'forever' (cool URIs)[3].

While this seems not very radical it really leads services to cast in stone exactly those things that are easy to keep fixed. At the same time REST allows server to change all other aspects.

Now, when you think about it, there is actualy not so much you can do when you evolve a service. You can add resources, you can add representation types provided for existing resources. You can remove links that are not mandatory.

Only the latter one actually can affect clients negatively. However, in a networked system it is an illusion that a client can control what a service chooses to do. In an OO world, the API creates that illusion but if an item is out of stock at Amazon an RPC call to item.purchase() will not succeed even if the Item class provides the purchase() method.

All that REST does is to emphazise this reality by asking the clients to look for the state transition (the purchase form or link or whatever) and *if* it is present to go about purchasing the item.

Sorry, much of this is probably unclear at the moment. I'll be happy to try again.

[3] This is why it is ok to bookmark the URI of an order and use it as a future entry point into the application

> I don't think it would be cluttering this thread to discuss this as I think its fundamental to the kind of client API we could create.

Yes, I just wanted to stay away from trying to shove that into the other mail.


> Marc.
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:

 Jan Algermissen, Consultant
 NORD Software Consulting