So far the only significant operation that we enabled our RestAgent to perform is NavigateTo().  However, for a RestAgent on a mission, going places is only half the story, the other major purpose of the agent is to gather content.

I was planning to show some real examples of missions using Stack Overflow’s API, but I ended up spending so much time explaining why it currently would not work, that my points were lost.  So forgive me as I continue with a somewhat more hypothetical example.  We are going to use an instance of our RestAgent to do a mashup of Twitter users and Stackoverflow users.

var agentFielding = new RestAgent(new HttpClient()); 

agentFielding.RegisterMediaType(“application/twitterdoc+xml”,
                                    new TwitterMediaHandler());
agentFielding.RegisterMediaType(“application/stackoverflowdoc+xml”,
                                    new StackOverflowMediaHandler());

In the following code, Agent Fielding retrieves my Twitter followers and attempts to find matching accounts on Stack Overflow.  In order to interpret the representations that will be retrieved from these two sites, we are going to pretend that these sites actually return non-generic media types and we register handlers for these media types that will transform the wire representation into strong types.

The first step is to navigate Twitter and retrieve the user profiles of my followers:

agentFielding.NavigateTo(new Uri(“http://api.twitter.com/”));
var userSearch = agentFielding.CurrentLinks(“UserSearch”);
userSearch.SetParameter("darrel_miller”);
agentFielding.NavigateTo(userSearch);

var followersLink = agentFielding.CurrentLinks[“Followers”);
agentFielding.NavigateTo(followersLink);

var twitterUserProfiles = new List<TwitterUserProfile>();
var followerLinks = agentFielding.GetCurrentLinks(l=> l.Relation.Name == ”Follower”];
foreach(Link followerLink in followerLinks) {

  var twitterProfile = agentFielding.GetContent(followerLink).ReadAsTwitterUserProfile();
  twitterUserProfiles.Add(twitterProfile);

}

Now we have a list of TwitterUserProfile objects from which we can retrieve the name and search on Stack Overflow.

agentFielding.NavigateTo(new Uri(“http://api.stackoverflow.com/1.0/”)); 

agentFielding.NavigateTo(agent.CurrentLinks[“Users”]);
var searchLink = agent.CurrentLinks[“Search”];
var foundProfiles = new List<StackOverflowUserProfile>();
foreach(var profile in twitterUserProfiles) {   searchLink.SetParameter(profile.UserName);
  agentFielding.NavigateTo(searchLink); 

  var matchingUserLinks = agentFielding.GetCurrentLinks(l=> l.Relation.Name == ”User”])
  foreach(Link userLink in matchingUserLinks) {
       var content = agentFielding.GetContent(userLink);
       foundProfiles.Add(content.ReadAsStackOverflowUserProfile();
  }
}

Don’t get too hung up on the precise details of the above, there is a bit of smoke and mirrors going on.  I’m really just trying to convey the concept that the same agent class can be used to navigate multiple different services.  This brings the concept of the uniform interface a little further into the client code. 

My hope is that in the future that REST api producers will supply media type handlers for their custom media types and we can use a standardized agent like interface for navigating any REST api.  There will be no need the API producers to create complete client side facades.

There is still plenty of coupling in the above example, when it comes to handling specific representations and knowing about the existence of specific links, there is plenty of service specific code.  This is especially true of these type of scripted or (machine to machine) interactions.  Machines are really dumb, so they need to understand a lot of specifics of the services that they are interacting with.  In the next article I’m going to start digging into how you can use an agent to react to a human driven application, and that will  further reduce the coupling. 

var agent = new RestAgent(new HttpClient());
agent.NavigateTo(new Uri(“http://api.stackoverflow.com/”)); 
var questionsLink = agent.CurrentLinks[“Questions”]
agent.NavigateTo(questionsLink);
var questions = agent.CurrentContent.ReadAsJson(); 

Before I talk about the magic that is going on under the covers here, let me take a little jab at my friend StackOverflow.  The above code would not work, because when the team created the api, they chose not to put a root representation on the API. Making the request to the root of the api actually redirects to an html page with API documentation.  I’ve tried scraping the urls out of that document, but it is proving to be painful.

The Link Class

The CurrentLinks property makes a dictionary of links available based on the links contained in the current content and potentially links that were included in the header.  You will notice that the second call to NavigateTo passes a “Link”, not a URL.  So what’s the difference?  Here is a basic implementation of the Link class:

public class Link {

  public string Name{ get; set;}
  public LinkRelation Relation{ get; set;}
  public Uri Url { get; set;}
  public HttpMethod Method { get; set;}
  public HttpContent Content {get; set;}

  public Dictionary<Parameter> QueryParameters {get; set;}
  public Dictionary<Parameter> PathParameters {get; set;}

}

The Link class holds plenty of additional information that is needed to allow the NavigateTo method to transfer to a new state.  The Link objects are created from information contained in retrieved hypermedia content.  If the HttpMethod is a PUT or a POST then the Content property can be used to hold the entity that will be sent to the origin server. 

The LinkRelation property is critical concept.  The Link Relation is one of the two points of coupling between the client and the server.  The other being the media-type.  From an architectural point of view the Link Relation describes the relationship between two resources.  For example, if you have a representation A that contains a link to resource B with the relation “edit”, this can be interpreted as B allows you to “edit” A.  IANA keeps a registry of well known link relations here http://www.iana.org/assignments/link-relations/link-relations.txt.  The WHATWG group are also maintaining a list here http://wiki.whatwg.org/wiki/RelExtensions.

From an implementation perspective, the Link Relation can be used to tell the client mechanical information about how to perform the HTTP request.  For example, what HTTP method to use, what content needs to be posted back to the server, if any. It also can be used to tell the client what query string parameters are valid.  Arguably you can introduce any kind of arbitrary significance to a link relation as long as you are prepared to put up with the client/server coupling.

I have been experimenting with implementing LinkRelation as an actual class instead of just an identifer.  Many different link relations have similar sets of behaviour and by creating a base class with some standard attributes it is possible to represent specific link relations as derived classes and still have plenty of generic mechanisms that process links without scattering the code base with fragile switch statements.  Hopefully as we go into more detail I will show some examples that take advantage of this LinkRelation base class.

So far I have only used very simple URI templates and so my needs have been satisfied with just a collection of query parameter values and path parameter values.  The current draft of the URI template specification introduces many more variants that I could be supported by the Link class.

The Name property is the black sheep of the Link class.  I’m not convinced that we really need this property.  However, I include it to support the scenario where there are multiple links within a hypermedia document that has the same LinkRelation.  How a client is supposed to differentiate between those different links without introducing out of band coupling is not always clear to me.  If the current representation is to be rendered to the user as a set of links then the user should be capable of deciding which they wish to follow.  However, in a scripted (ie. machine 2 machine) scenario, it becomes highly suspect if the script starts referring to link names.  Depending on how precise the media type, is, the link names could be pre-specified in the media-type.  Or code-download could be used to activate links with particular names.  The final solution that I have seen is to drop the name property completely and use very specific link relation values.  I’m not a big fan of this approach because I think it leads to the same explosion problems as using extremely specific media-types.  Highly specific media-types and link relations destroy the possibility of serendipitous reuse.

Hypermedia Content

So now, you have an idea of how I handle links, let’s look at how those links get created in the first place.  As I mentioned before, the CurrentLinks dictionary is populated from the CurrentContent.  The question of course is how can the generic RestAgent know how to pull links out of content that could be any media type.  The solution is a plug in model that allows handlers to be registered in a media type handler registry. 

Behind the scenes I use MEF to load up the media type handlers, but I stuck an interface in front, mainly because I’m not very experienced with MEF and I wasn’t exactly sure how to setup unit tests using MEF.  With the interface I can easily create a fake registry.

public interface IHandlerRegistry {
        IMediaTypeHandler GetHandler(ContentType contentType);
    }

Media type handlers I will cover in more detail at a later date.  All we care about for this series of articles, is that they can be used to do two things:  1) they can convert the stream of bytes coming from the http response into a class that implements IHypermediaContent and 2) they can create and run a controller with RunController(HttpResponseMessage response) method that will “do” whatever that media type is supposed to do.  I realize that sounds very vague, but vague is good when we don’t want to introduce coupling .

public interface IMediaTypeHandler {
    IHypermediaContent GetContent(HttpContent content);
    IMediaTypeController RunController(HttpResponseMessage message);
}

For this article I’m going to ignore RunController and we will get to human driven clients in an upcoming article.  That leaves us with GetContent that returns an IHypermediaContent interface.  That interface looks like this:

public interface IHypermediaContent {
       IDictionary<string, Link> Links { get; }
   } 

Not exactly complex to implement!  Consider what it would take to write a handler that processes, HTML, XHTML, Atom Feeds, HAL, or even one that attempts to scrape links out of Json or generic XML based on some link convention. 

Magical Links

Pulling this all back together, when you navigate the agent to a particular location on the web, the agent will identify the media type of the returned response, determine a handler for that media type, allow the handler to process the bytes and extra the links and store them in a dictionary available via the CurrentLinks property of the agent.

Here is a completely hypothetical use of the RestAgent to crawl safe links on a site:

var agent = new RestAgent(new HttpClient(), new Uri(“http://mythical.com/hypermediaService”));
ExploreLinks(agent);

public void ExploreLinks(RestAgent agent) {
var links = CopyLinks(agent.CurrentLinks);
foreach(Link link in links) {
    if (Link.Method == HttpMethod.GET && Link.LinkRelation.RequiresParameters == false) {
        agent.NavigateTo(link);
        Explore(agent);
    }
}
}

To keep things simple, I only traverse links whose LinkRelation specifies a GET is the appropriate verb and only links that do not require parameters. 

I realize that this is still not a very useful example, but enough of the pieces are in place so that in the next article I will talk more about how to get the agent to actually do something useful.

I write distributed business applications for a living and to date, it appears that I end up supporting the code I write for at least 10 to 15 years.  When ever you deploy and update distributed systems there is a nasty side effect of having different components to update and trying to deploy them simultaneously is rife with pitfalls.  Deploying an update to a server compared with updating software on 50 client machines is just a completely different set of problems and keeping them synchronized can be challenging. 

I realize that many people would argue that using a web browser as a client platform would solve my distribution problems.  It would solve the distribution problem, but it would also introduce a whole host of other problems for the types of applications I write.  Browser based apps are awesome for many things, some things they are not so awesome for.

The REST constraints allow you to manage the coupling between the distributed components and allow them to evolve more independently. This allows the system as a whole to evolve incrementally over long periods of time.  I need this kind of robustness in my line of work.

In the three years that I have been building RESTful systems I have seen lots written about how to design and implement RESTful APIs but very little has been written about how REST client applications need to be written.  The few people I have seen talk about it are Stu Charlton and Guilherme Silveira.

This is hopefully the first in a series of blog posts where I cover what I am learning about writing client applications that are part of a RESTful distributed system.

REST clients are a different breed

One of the core concepts when designing a REST client is the notion of Hypermedia as the Engine of Application State.  I’m not going to try and explain what I think it means, as many people far more eloquent than I, have tried and yet its meaning is still much debated.  Instead, I would prefer to show some code that I believe embodies the concept.

My REST client applications are built around a class called RestAgent.  I like to imagine my instance of the RestAgent class as little guy travelling across the web making requests and fetching data on my behalf [1].  This agent is responsible for holding all of my application state and for transferring state to and from origin servers.

In its most simple incarnation the class looks something like:

public class RestAgent(HttpClient client) {

  private Uri _CurrentLocation;
  private HttpContent_CurrentContent;

  public void NavigateTo(Uri url) {

    _CurrentContent = client.Get(url).Content;
    _CurrentLocation = url;
  }

}

The RestAgent itself does not know any of the nitty gritty details of how to do HTTP interactions, so I need to provide it with some kind of Http client library.  Obviously, I’ve chosen to use the Microsoft Http client, but in theory any library could work. 

At this point the only thing that the RestAgent is really capable of doing is navigating to the provided url and retreiving the returned content.  The important concept here is that at any one point in time, the RESTAgent can only be in one place.  As we expand on the capabilities of the agent we will allow it to accumulate content during its travels and the aggregate of all of that content will be the “application state”, but if our client application really needs to be in multiple places at once, then we will create multiple agent instances.

For just a small taste of how you might use this RestAgent,

var agent = new RestAgent(new HttpClient());

agent.NavigateTo(new Uri(“http://api.stackoverflow.com/1.0/questions”)); 
var questions = agent.CurrentContent.ReadAsJson();

agent.NavigateTo(“http://search.twitter.com/search.atom?q=@darrel_miller”) 
var mentions = agent.CurrentContent.ReadAsSyndicationFeed();

In the next post, I’ll talk more about hypermedia and how the agent can use links from hypermedia content to travel further and gather more content.

[1]  I originally wanted to call this class AgentFielding to anthropomorphize the class even more, but it seemed a touch presumptuous

A canary in a coal mine.

I have been waiting for a question like this for close to a year now. It was inevitable that this day would come and I am sure we are going to see many more questions like this in the coming months.

The warning signs

You are absolutely correct, it does take longer to build RESTful clients than SOAP clients. The SOAP toolkits take away lots of boilerplate code and make client proxy objects available with almost no effort. With a tool like Visual Studio and a server URL I can be accessing remote objects of arbitrary complexity, locally in under five minutes.

Services that return application/xml and application/json are so annoying for client developers. What are we supposed to do with that blob of data?

Fortunately, lots of sites that provide REST services also provide a bunch of client libraries so that we can use those libraries to get access to a bunch of strongly typed objects. Seems kind of dumb though. If they had used SOAP we could have code-gen’d those proxy classes ourselves.

SOAP overhead, ha. It’s latency that kills. If people are really concerned about the number of excess bytes going across the wire then maybe HTTP is not the right choice. Have you seen how many bytes are used by the user-agent header?

Yeah, have you ever tried using a web browser as debugging tool for anything other than HTML and javascript. Trust me it sucks. You can only use two of the verbs, the caching is constantly getting in the way, the error handling swallows so much information, it’s constantly looking for a goddamn favicon.ico. Just shoot me.

Readable URL. Only nouns, no verbs. Yeah, that’s easy as long as we are only doing CRUD operations and we only need to access a hierarchy of objects in one way. Unfortunately most applications need a wee bit more functionality than that.

The impending disaster

There are a metric boatload of developers currently developing applications that integrate with REST services who are in the process of coming to the same set of conclusions that you have. They were promised simplicity, flexibility, scalability, evolvabilty and the holy grail of serendipitous reuse. The characteristics of the web itself, how can things go wrong.

However, they are finding that versioning is just as much of a problem, but the compiler doesn’t help detect issues. The hand written client code is a pain to maintain as the data structures evolve and URLs get refactored. Designing APIs around just nouns and four verbs can be really hard, especially with RESTful Url zealots telling you when you can and cannot use query strings.

Developers are going to start asking why are we wasting our effort on support both Json formats and Xml formats, why not just focus our efforts on one and do it well?

How did things go so wrong

I’ll tell you what went wrong. We as developers let the marketing departments take advantage of our primary weakness. Our eternal search for the silver bullet blinded us to the reality of what REST really is. On the surface REST seems so easy and simple. Name your resources with Urls and use GET, PUT, POST and DELETE. Hell, us devs already know how to do that, we have been dealing with databases for years that have tables and columns and SQL statements that have SELECT, INSERT, UPDATE and DELETE. It should have been a piece of cake.

There are other parts of REST that some people discuss, such as self-descriptiveness, and the hypermedia constraint, but these constraints are not so simple as resource identification and the uniform interface. The seem to add complexity where the desired goal is simplicity.

This watered down version of REST became validated in developer culture in many ways. Server frameworks were created that encouraged Resource Identification and the uniform interface, but did nothing to support the other constraints. Terms started to float around differentiating the approaches, (HI-REST vs LO-REST, Corporate REST vs Academic REST, REST vs RESTful).

A few people scream out that if you don’t apply all of the constraints it’s not REST. You will not get the benefits. There is no half REST. But those voices were labelled as religious zealots who were upset that their precious term had been stolen from obscurity and made mainstream. Jealous people who try to make REST sound more difficult than it is.

REST, the term, has definitely become mainstream. Almost every major web property that has an API supports "REST". Twitter and Netflix are two very high profile ones. The scary thing is that I can only think of one public API that is self-descriptive and there are a handful that truly implement the hypermedia constraint. Sure some sites like StackOverflow and Gowalla support links in their responses, but there are huge gaping holes in their links. The StackOverflow API has no root page. Imagine how successful the web site would have been if there was no home page for the web site!

You were misled I’m afraid

If you have made it this far, the short answer to your question is those APIs (Netflix and Twitter) do not conform to all of the constraints and therefore you will not get the benefits that REST apis are supposed to bring.

REST clients do take longer to build than SOAP clients but they are not tied to one specific service, so you should be able to re-use them across services. Take the classic example, of a web browser. How many services can a web browser access? What about a Feed Reader? Now how many different services can the average Twitter client access? Yes, just one.

REST clients are not supposed to be built to interface with a single service, they are supposed to be built to handle specific media types that could be served by any service. The obvious question to that is, how can you build a REST client for a service that delivers application/json or application/xml. Well you can’t. That’s because those formats are completely useless to a REST client. You said it yourself,

you have to make "guesses" as to what will come back across the pipe as there is no real schema or reference document

You are absolutely correct for services like Twitter. However, the self-descriptive constraint in REST says that the HTTP content type header should describe exactly the content that is being transmitted across the wire. Delivering application/json and application/xml tells you nothing about the content.

When it comes to considering the performance of REST based systems it is necessary look at the bigger picture. Talking about envelope bytes is like talking about loop unwinding when comparing a quick-sort to a shell-sort. There are scenarios where SOAP can perform better, and there are scenarios where REST can perform better. Context is everything.

REST gains much of its performance advantage by being very flexible about what media types it supports and by having sophisticated support for caching. For caching to work well though nearly all of the constraints must be adhered to.

Your last point about readable urls is by far the most ironic. If you truly commit to the hypermedia constraint, then every URL could be a GUID and the client developer would lose nothing in readability.

The fact that URIs should be opaque to the client is one of the most key things when developing REST systems. Readable URLs are convenient for the server developer and well structured URLs make it easier for the server framework to dispatch requests, but those are implementation details that should have no impact on the developers consuming the API.

The Twitter API is not even close to being RESTful and that is why you are unable to see any benefit to using it over SOAP. The Netflix API is much closer but it’s use of generic media types demonstrates that failing to adhere to even a single constraint can have a profound impact on the benefits derived from the service.

It may not be all their fault

I’ve done a whole lot of dumping on the service providers, but it takes two to dance RESTfully. A service may follow all of the constraints religiously and a client can still easily undo all of the benefits.

If a client hard codes urls to access certain types of resources then it is preventing the server from changing those urls. Any kind URL construction based on implicit knowledge of how the service structures its urls is a violation.

Making assumptions about what type of representation will be returned from a link can lead to problems. Making assumptions about the content of the representation based on knowledge that is not explicitly stated in the HTTP headers is definitely going to create coupling that will cause pain in the future.

Should they have used SOAP?

Personally, I don’t think so. REST done right allows a distributed system to evolve over the long term. If you are building distributed systems that have components that are developed by different people and need to last for many years, then REST is a pretty good option.

I have two questions for Dion and a few comments.
1) Have you read (not just skimmed a few times) Roy’s dissertation on REST?
2) Have you written both a REST service and a REST client that is in production today?

With all due respect, without actually creating REST applications, I don’t think anyone is qualified to attempt to define principles relating to REST and based on your Twitter bio:

Internationally recognized business strategist, enterprise architect, keynote speaker, author, blogger, and consultant on Web 2.0, SOA, and next-gen business

you sound like a talker, not a walker.  Forgive me if I am wrong.

Here are my comments on the suggested principles, I’ve tried to be as constructive as I can muster:

Principle #1: I think it is a significant oversimplification to refer to a resource  as data. 

Principle #2: Can you clarify what you mean by "favor granularity and depth in linkage"?

Principle #3: I am pretty sure no-one has ever said that URIs should be self descriptive.  In REST the request message should be self-descriptive, the URI being just one part of the message.   The statement “URI should indicate what data format is being used and indicate nested elements with URL segmentation” is way too strong, maybe if you replace “should” with “can”.

Principle #4:  This idea that all legacy databases should be exposed as data-oriented REST apis is crazy-talk.  REST is an architectural style for building distributed APPLICATIONS.  I.e. Exposing functionality over the web, not just data. Your example of cloud computing API’s is a perfect example.  The Sun Cloud API is one of the best REST examples out there at the moment, but it exposes functionality for manipulating those cloud applications.  Functions like turning the instances on and off.  It’s far more than just exposing data.

Principle #5:  You seem to be describing benefits rather than a principle.

#6:  Ok

#7: I don’t get this concept at all.  Does this mean we should all be using text/plain if we want the widest audience?

#8: Maybe I don’t want my resources to crawled by an SEO.  Even if I do, conforming to the uniform interface and delivering standard format representations should be sufficient to meet any search engine requirements.

#9:  “higher realized value”?  Are you sure this isn’t another one of those spoof manifestos?

#10: I think you are referring to the idea that a resource should only have one canonical URI.  I see this topic debated regularly and I do not yet see any consensus.

Ok, I give up for the moment, I’m a bit too depressed to continue.

Let me start by quoting the most important paragraph from the document that explains how OData extends AtomPub.

AtomPub, as specified in [RFC5023], in combination with the extensions defined in this document, is appropriate for use in Web services which need a uniform, flexible, general purpose interface for exposing create retrieve update delete (CRUD) operations on a data model to clients. It is less suited to Web services that are primarily method-oriented or in which data operations are constrained to certain prescribed patterns.

Let me paraphrase that.  If all your service is going to do for your client is “CRUD” on generic data then OData is appropriate.  As long as everyone keeps this in mind going forward we should not run into too much trouble.  However, there is a problem with this statement.  REST is not really appropriate for doing CRUD.  Harry Pierson sums it up best here.  What is worse, is that I am seeing some of the people behind the OData spec equating OData with ODBC. 

The problem is that ODBC allows clients to initiate transactions across multiple requests. REST does not allow this as it would violate the stateless constraint.  REST does not need this because it is intended to address a completely different layer of the application architecture than ODBC.  REST provides a way to deliver Domain services.  I.e.  If you maintain weather data, REST provides you a easy way to expose “Today’s Weather”, “Last Week’s weather for Detroit”, “Average Rainfall in Orlando for the month of June”.  ODBC is aimed at the layer that exposes the data points for a specific place at a specific date and time. 

ODBC exposes dumb data, REST exposes intelligently presented information.

In an ODBC application it is the client that does something intelligent with the data before presenting it to the user.  In a REST application, usually the client simply makes the “intelligent information” pretty.  REST and ODBC are not comparable.

So is OData useful?  Absolutely it is useful to people who want to manipulate generic information, like for example Sharepoint lists, or data to feed into PowerPivot or Excel.  If you have a need to expose a generic data store to a client that will do graphing, statistical analysis, or some kind of visualization like rendering Mars Rover data then it could be very useful. 

However, if you want to provide a service that delivers intelligent information that is specific to a particular domain then I believe and apparently the authors of the spec believe that OData is not appropriate.

Beyond my fear of developers attempting to use OData for unintended purposes there are few other things that I think should be fixed in the OData spec. 

The Atom Entry content element should not use application/xml as the media type.  The content contains XML that is specifically related to the Entity Data Model and should be identified as such.  A media type such as application/EDM-Instance+xml may be sufficient.  What would be even better is if that content element contained a link to the CSDL file that defines the EntityType and that is currently accessed by constructing an URI with [Service]/$metadata.  Oh yeah, and maybe a precise media type on the metadata would be good too!

Client side URI construction is really nasty habit to get into.  I think for the most part, MS can get away with the construction of query parameters like $skip, $top, and $orderby, but to actually construct the path segments of a URI is just going lead to client-server coupling that will hurt in the future.

I haven’t read the entire OData spec in detail but it is interesting to see the complications that are introduced because they have not strictly followed the hypermedia constraint.  For example, it has become necessary to create custom HTTP headers to manage versioning of the “protocol” due to the use of client constructed URIs.  If those URIs were delivered as Links with rel attributes then the versioning would be limited to the media type of the content.  Yeah, I realize that you can’t create links for every combination of query parameter/ sub resource, but hey, I’m not the one saying that creating a REST interface for generic data was a good idea in the first place .

It is fascinating how difficult it is to beat the RPC mentality out of people.  Even though the OData spec is built on top of AtomPub, the authors have gone to great lengths to document the OData protocol in RPC terms and then map the RPC call to an HTTP request.  When you find yourself creating documentation titles like “RetreiveEntitySet Request”, “RetreiveEntity Request”, “RetreiveComplexType Request”, “RetreivePrimitiveProperty Request” and there is actually some valuable information that distinguishes one of those requests from the other then you are violating the uniform interface.  The idea is that the documentation can read “Use HTTP GET to retrieve representation of the resource from the URI”. Look at how simple the AtomPub spec is in comparison.

I think it is great that Microsoft have recognized the value of a RESTful protocol like AtomPub and they have taken the steps to incorporate this type of interface into many of their products.  I understand what they are trying to do with their URL construction techniques, I know exactly why they have introduced a MERGE verb and have created a batch request mechanism, because I too have been down this path before.  However, while there some areas they are justified in straying from the REST constraints, there are others that are definitely not and the protocol is suffering from it.

However, the new client side library is designed to make it easier to talk to HTTP endpoints and it seems to be quite nice.  It is 3500 lines of code, so there is a fair bit of stuff in there, layered on top of HttpWebRequest and I was curious to see what it could do.

I started by looking at the enclosed sample, unhelpfully named “WpfSample” and I got a little sidetracked from my exploration.  This sample is actually a very neat little http request builder tool.  I know this is a cool tool to have, because I have an almost identical one that we built to help us test REST services.  Testing with real web browsers is really annoying because they do all sorts of magic stuff behind the scenes, they are very picky about what content-types they will render and they keep trying to find a favicon! 

Anyway, I was curious to see how this tool made use of the HttpClient class but I was rather dismayed to see all of the code in the “code behind” of the Window1.xaml file.  This makes it really difficult to distinguish between what code is relevant to the web request and what is just UI gunk.  To add salt to the wound, it is a WPF app that uses no data binding and no Commands, just events manipulating the contents of UI elements.  It was a nice looking, handy WPF app that demonstrated this new spiffy HttpClient library with the architecture of a college student’s VB4 project.

Ok, I know it is just a sample.  However, everything that Microsoft puts out is viewed by people who are learning.  If Microsoft create samples with crappy architecture, why are we surprised when developers create applications with crappy architectures.

So despite the ton of work that I was supposed to be doing today, I refactored it.  I created an MVC type of structure with databinding and routed commands.  If you get the WCF REST Starter Kit and extract the zip file that gets put in the “C:\Program Files (x86)\Microsoft WCF REST” folder you will find a solution named Product.sln.  Just add my project which is in the zip file below and you will have, what I hope is a much easier to read version of the HttpClient sample.

http://www.tavis.ca/files/httpClientGui.zip

My interest in the trailing slash had been provoked by my attempts to use relative urls in some documents that I was returning from a REST server.  Sometimes the relative urls would work sometimes they wouldn’t.

The performance benefit discussion that I had found related to the fact that web servers will automatically redirect to an url with the trailing slash if the last segment points to a folder instead of file. 

e.g. A request to http://example.org/folder would actually be redirected to http://example.org/folder/default.htm (or whatever file is set as the default file)

As is probably obvious to anyone who has done any amount of web development, all relative urls processed by a web server are relative to the folder in which the containing file is located.  Mechanically, this means the last segment is of the url is stripped of and the relative url is added.  A detailed explanation of how a relative url is resolved can be found here.

The key point that I want to draw attention to is that the behaviour is pretty natural when you are pulling static files from folders on a web server.  It gets less obvious when you start using dynamically generated resources with the style of urls that are common in the REST world.

E.g.  Say you retrieve a resource such as http://example.org/customer/101 and it contains an element <link href="address"/>.  Common sense dictates that you are trying to get to http://example.org/customer/101/address, but that is not how it would be resolved.  The url would actually be resolved as http://example.org/customer/address

The problem is that the server no longer has a file/folder distinction, so the routing infrastructure doesn’t know whether it should append a slash to your url or not.

From what I’ve seen of Microsoft’s new URL routing infrastructure that is used by ASP.NET MVC and the WCF Rest toolkits, the url gets passed through with or without the slash depending on what the user typed.  This is a problem if you want to use relative urls in your representations.

I decided that I would include xml:base in documents so that at least I could be explicit about where my relative urls were relative to.  This way I don’t care if the source url ends with a slash or not.  I make sure that all my xml:base urls end in a slash and so far this strategy is working for me.

It is the hypermedia constraint that makes REST as a style
greater than the sum of its constraints. It is the focal point
and amplifier of all the constraints.  – Aristotle Pagaltzis

Well-designed URIs are great, but they don’t influence whether something is RESTful or not.

- Stefan Tilkov

I was most struck by what Roy seems to be saying is required to document a REST Api.

1. A description of the media types that are used throughout the API.
2. A root Url.

That is it.  If you look at most API specs you will see a long laundry list of the endpoints that can be used to access various pieces of functionality.  In REST, you don’t want to provide a list of endpoints because then you are allowing the client to bake that knowledge into its implementation.  That’s coupling.

I’m going to reach a little here and add some of my own conclusions.  You can couple on the media types.  If you need to create your own media type to allow the client to process the data on the server, then so be it.  At some point the client has to understand what to do with the data it is being sent. 

However, don’t couple on endpoints, there is really no need.  Use the root url to deliver some kind of discovery document that allows the client to find the other available resources.

It’s kind of like how a web site works…