You can’t achieve REST without client and server participation

Posted by Glenn Block on March 11, 2012

Recently I have been having a bunch of discussions around REST and whether or not the client participates in the RESTfulness of a system. Until now I’ve been saying that REST is confined to the server. I now realize that was wrong. Having a server which adheres to the constraints without clients that obey the same constraints will NOT yield the full benefits of REST.  There’s a recent thread on this topic on the rest-discuss list here with some varying opinions.

My particular learning here is that when building RESTful systems we need to start paying more attention to the client*. The more I learn about REST, the more I realize that the client is where a lot of the hard work is.

Note: When I use client here I don’t mean the connector, I mean the user-agent which outside of HTTP circles is conventionally referred to as the client.

Here are the high level points.

  • A RESTful system has a shared set of responsibilities between client and server. To truly realize the benefits of REST both client and server have to be good citizens.
  • The server is the critical path. It’s responsibility is to expose resources in a manner that is consistent with adhering to the constraints. That means it sticks to the uniform interface (headers, media types), supports caching, uses hypermedia etc. If it does not, then it will prevent the benefits for all clients.
  • The client must also adhere to REST constraints. If it does not, then the overall benefits of REST are not achieved within that system. It’s responsibility is to consume resources in a RESTful manner, i.e. use the uniform interface, consumes hypermedia, obeys caching requirements, etc.
  • A client not obeying the rules does not necessarily remove all benefits of REST for the server, though it can impact them significantly if it is the ONLY client.

In many situations the clients (user agents) are out of you control as they are owned by third parties, so does that mean you should give up on trying to achieve the benefits of REST? I don’t think so, but it does mean more attention needs to be paid to clients / guidance given on how to build those clients in an evolvable fashion. Darrel Miller has started down this path in his recent post on a hypermedia client maturity model.

I think there’s much more discussion needed on this topic, For more RESTful systems to be realizable, we as industry need to offer more infrastructure / reusable components to make it easier for folks to build such clients.

Beyond that let me not forget to emphasize that you don’t necessarily NEED to build a system in a RESTful fashion. There are many factors that play in which is beyond the scope of this post.

Interested in your thoughts.

This entry was posted in HTTP, Hypermedia, REST. Bookmark the permalink. Follow any comments here with the RSS feed for this post.
  • http://wizardsofsmart.net/ panesofglass

    Interesting that you would say the client bears the burden of the “hard work.” I’m interested to see exactly why the client is more difficult. It seems that the client is afforded some ease in that the links provided, some in the form of templates, allow the client to select and/or expose these “actions” without having to be built with this knowledge from the beginning. At least, that seems to be the case if the client is adhering to the constraints. Help me understand where this becomes harder.

  • http://wizardsofsmart.net/ panesofglass

    I agree that “REST” has been abused too much to make it meaningful any longer. I found this post useful for defining terms: http://theamiableapi.com/2012/03/18/rest-design-philosophies/

  • http://wizardsofsmart.net/ panesofglass

    All you really found is that a client built for RPC doesn’t easily transition to a hypermedia model. Also, your first point shows that building URIs from scratch is not “easier,” as Google’s changes broke your application. Unless you think broken functionality is easier, which I suppose is true.

  • Leonid Shirmanov

    Is there any way to propagate CorrelationManager’s ActivityId through WebAPI REST service and back to the client?

  • Richard Makepeace

    Sounds like a very interesting project, I’m hoping to do something similar with the next major version of the product I’m working on at the moment.  You mentioned that the server was providing a UI template to the client which sounds like a good idea to deal with the problems I mentioned in my previous comment.

    I’d love to see a sample of your UI template structure if possible.  Do you feel you could easily adapt the existing UI template to create a website (or a rich client on a different platform) along similar lines?  I’ve been asked to create both a rich client and web interface to a single REST service so I’m just looking at ways to try and make all my clients good REST citizens.

  • http://darrelmiller.myopenid.com/ Darrel Miller

    My post on the Hypermedia Client Maturity Model [1]  was an attempt at identifying where clients can improve the way they interact in a hypermedia system.  Although, I’m not that happy with the way it is currently, and I need to make a bunch of revisions to it.

    [1]http://www.bizcoder.com/index.php/2012/03/07/hypermedia-client-maturity-model/

  • http://darrelmiller.myopenid.com/ Darrel Miller

    I have been able to build a rich LOB app that uses hypermedia to guide the client.  I do stuff like order entry and invoicing and it is able to provide exactly the same rich experience that regular c/s apps do.  The key for me was identifying that the domain of the client was “data entry forms” and once you encapsulate all the relevant concepts into a media type then from the client’s perspective whether the user is entering a price for invoice or a purchase order is irrelevent.  As long there is a way to format the result, validate the entry and display related information after the input.  
    The trick to rendering data in a generic way is to have the server provide you a UI template and use data binding to fill the template.
    The other key factor when building clients this way is to build them so that they react to a response from the server instead of expecting a response from the server.  That way, when, one day, the server decides to change the response it gives the client does not break.

  • http://blogs.msdn.com/gblock Glenn Block

    I think Darrel Miller is on the right track with the work he is doing around his RestAgent. It leads you down a path of building a client that navigates the server via links. It helps the client wire up handling code for the different transitions. 

    RESTfulie also has some nice stuff with their whole DSL for hypermedia.

  • http://www.facebook.com/people/Theo-Albers/100001542370471 Theo Albers

    I didn’t assume that you where talking about an UI. I assumed that most clients, consumers of RESTful services, sooner or later will have to render something useful to a human being.  We can challenge that assumption. The other category of clients would be aggregation services for crawling linked data, in the semantic web context?
    So if you accept that a large chunk of clients directly render content based on RESTful streams *and* clients have to play well in the RESTful game, we should analyse how such clients can use REST effectively and when they would be a bad citizen.
    I fully agree that the server is the critical path. Basically this is no different to a database server: it too has to handle different client profiles, cache, provide resources, etc.  But what additional infrastructure / components are needed in your opinion to boost RESTful service adoption? For building generic clients?

  • Richard Makepeace

    While I accept that a client doesn’t necessarily mean a UI directly surely it’s an issue that’s worth discussing as I think the majority of clients have to interact with a user at some point. Also if there is no end user interface then who exactly is benefitting from links being removed unless your program is some how smart enough to work out what to do with extra options.

    You talked in the other reply about the client having the choice of where to transition to but if you don’t have a user interface I can’t see how you make that decision when new options that weren’t there when you coded the client appear unless you’ve got a seriously smart client. I am open to the suggestion that my idea of the usage scenarios of REST based systems is completely wrong so please tell me if you think I’m suggesting something that is outside what you consider to be a good use for REST.

  • http://blogs.msdn.com/gblock Glenn Block

    ”
    I guess my point is that many hypermedia advocates assume it is always a good idea to drive client state transitions from the server and I think I just stumbled upon an example where it is not.”

    Hmm, I don’t think hypermedia advocates that. Hypermedia is all about putting the power in the clients hands. What it does advocate is having the server offer clients the choices of where it can transition to. It is up to the client to choose from the available set.

  • http://blogs.msdn.com/gblock Glenn Block

    I agree that it is easy for clients to ignore links and it happens commonly. That is because navigating links within responses has not been the prevalent practice. The advantage of that practice changing however is preventing the exact types of failures you are hitting.

  • http://blogs.msdn.com/gblock Glenn Block

    I think you are making a similar mistake assuming I am talking about a UI, client != UI necessarily ;-)

    I am not at all suggesting you just throw links to the user interface so I don’t know where that comes from. 

    The context of this discussion is not about resource fetching. It is about clients and servers cooperating to provide an overall benefit to to the system.

  • http://www.facebook.com/people/Theo-Albers/100001542370471 Theo Albers

    I think you make the typical techie mistake: you start at the server end and think “how can I do something smart to get some user interface”. You should start with the persona and try to understand how the user would like to interact with the system. You hopefully will design an ergonomic user interface this way. A data entry intensive application is significantly different from a magazine style application which is hyperlink intensive.
    So when you say we have to pay more attention to the client, you’re right. Not sure though that intelligent resource fetching will help. You would need some replicated intelligence on the client to provide a convenient user experience. Simply walking the resource hierarchy and dumping data in user interface panels is not enough. How would you translate an invoice resource graph including a customer link, invoice line links, address links, etc. into something automatically rendered and still usable? The software industry has tried that several times in the past and failed miserably.

  • http://theamiableapi.com/ Ferenc Mihaly

    A few weeks ago I was fooling around with a Goggle API. I had it working then suddenly one morning it did not work anymore. It turns out that Google made some updates and slightly changed the URL pattern. I wasn’t using the links returned by the previous calls because it was cumbersome to store them and pass them around in the proprietary framework I was using.

    I think this proves two things.

    1. It is easy for clients to ignore the links returned and build URIs from scratch like I did even if you use hypermedia

    2. For clients written from scratch it might be easy to follow links, but if the client is like mine a three hundred thousand line legacy behemoth, chances the state transitions already in client code and state transitions hypermedia tries to drive it through coinciding are nil.  

    I guess my point is that many hypermedia advocates assume it is always a good idea to drive client state transitions from the server and I think I just stumbled upon an example where it is not.

  • Evan Larsen

    It would be nice to see more examples of REST using the web api.  I have yet to see any good examples above here is a simple CRUD api controller.. w/out validation.   I know the P&P team already have their road map for the next few years but it would be nice to see something from them creating a full REST app using hypermedia. Maybe, convert their Project Silk to be RESTful?  just some wishful thinking.

  • Anonymous

    This sounds like a specific application of Postel’s Law.

  • http://blogs.msdn.com/gblock Glenn Block

    It’s called creating the post via the codebetter web portal :-)

  • http://blogs.msdn.com/gblock Glenn Block

    Nothing about this post is trying to force REST on anyone. I am observing the relationship the client has to the RESTfulness of a system. This is part of my own learning. Feel free to ignore it.

  • Ignacio Fuentes

    Well, I guess the term REST expert is not strictly defined. But you are the person Microsoft chose to build it’s REST framework (wcf web api -asp.net web api) and that by itself already says something about your expertise. 
    In any case, my point is that we could be much more productive by worrying about good practices on building http web apis without caring that much if a specific practice can or cant be considered part of the “REST spec”.

  • codebetter.com/glennblock

    I would not consider myself a REST expert, I am just a student. As I learn more I re-evaluate my previous assertions as I have new information. I don’t see that as a reflection on REST itself. Also as I said, you don’t have to build a RESTful system, in which case you can ignore this post.

  • Ignacio Fuentes

    I think that the mere fact that a REST expert like yourself has to be constantly changing his mind  just proves that the term REST almost serves no purpose other than confuse people… let’s just stick to HTTP web apis with a set of recommended practices for both client/server that developers can choose to follow or not.

  • Howard Dierking

    I just want to know where you got your time machine that enabled you to post from tomorrow… :)