Previous posts in this series:

• Working with WCF: Part One – Introduction and Your First Service
• Working with WCF: Part Two – Your First Host and A Bit About Configuration
• Working with WCF: Part Three – Connecting To Your Service With A Client pt. 1
• Working with WCF: Part Three – Connecting To Your Service With A Client pt. 2
• Working with WCF: Part Four - Data Contracts
• Working with WCF: Part Five - Message Contracts
• Working with WCF: Part Six – Fault Contracts

We’re gonna step out of the whole Web Bagels/WCF demo thing on this post so I can give you a brief primer on Representational State Transfer (REST).

The good news is that if you are reading this blog then you have used REST. The reason is that REST is the architectural basis for the Internet. When you opened your web browser of choice and typed www.jamescbender.com into the address bar and hit ENTER, the browser issued a request to the access resource located at www.jamescbender.com (whatever that may be) using the REST GET verb. In fact, if you’ve ever navigated to any website you’ve seen REST in action. That’s the basis of REST; clients make requests to servers using a Uniform Resource Identifier (URI) which, depending on which REST verb was used in the request, returns, created, alters or deletes the resource at the location specified by the URI. It’s that simple.

URI’s and You

There are two components of a REST request; the URI and the verb.

The URI is probably the easiest for most people to get their heads around. It’s the location of the resource on the Internet that we want to get/change/delete. We’ve all used websites before, and we generally access them by a URL. You can think of a REST services URI as it’s location. But there is a bit more to it than that. Consider the following list of URI:

www.GloboCorp.com/Departments

www.GloboCorp.com/Departments/Sales

www.GloboCorp.com/Departments/Sales/Employees/JohnDoe

www.GloboCopr.com/Departments/Sales/Employees/search?name=JohnDoe

The first thing to notice about all of these is that they are human readable. You may know nothing about Globo Corp., but you know that it has departments, one of those departments is Sales and it has an employee named John Doe. A big part of our ability to understand that is the hierarchy that the information is presented in. When creating URI’s for REST services it’s important to think about how you want your information to be accessed and conceptualized. In this case it makes sense to have the list of Departments as one of the “top level” branches in the hierarchy. For another company it may make sense to have Employees be the top level. It all depends on what your data is like and how you want it presented.

Another thing to note is the “Universal” aspect of the URI. These are simply locations on the Internet. There is no special decoder ring needed to access these; any application that can use HTTP, and can handle the content type of the response (text, a picture, a sound file, etc.), can use the resources located at these addresses. You could embed these URI’s in a document and anyone reading that document, assuming they had some sort of HTTP capable web browser and access to the Internet could get the resource that resides at that location.

Finally, since these are simply URI’s, and there is nothing special about them, they can be cached like any other URI. This is a big advantage over the SOAP based services we’ve been using up till now. Since there’s a certain amount of “magic” that happens when a SOAP service is invoked caching is difficult, usually involving some sort of customization on the host. Since REST is URI based most web servers provide the ability to cache right out of the box.

VERB – That’s what’s happening.

Once we have our resource location we need to specify what we want to do with the resource. These is where the HTTP Request Method, a.k.a. the  REST verb come into play. There are a variety of REST verbs available. The four are the most commonly used and you will use in your everyday like are the following:

• Get – returns the resource at the URI’s location
• Post – creates a resource at the URI’s location
• Put – alters the resource at the URI’s location
• Delete – delete the resource at the URI’s location

In addition to these four, you may start to encounter the HEAD verb as more service providers have begun implementing it. HEAD returns metadata about the resource at the location that you would get if you sent a Get verb.

The benefit of the verb paradigm in REST is that we have a standardized interface. Unlike SOAP based services we aren’t creating our own verbs like GetEmployee or CreateSale. Being able to understand the information hierarchy behind our URI’s and having a standard list of methods (verbs) we can use on those resources makes developing clients that use REST services much easier and more intuitive.

POX and JSON

So now we know how to request resources from REST based web services. But what are we getting back. In the Web Bagels example we’ve been using SOAP based web services, which in fact return SOAP messages. REST doesn’t use SOAP. So what are our options?

POX

One option for our response is Plain Ol’ XML (POX). Like SOAP, our data comes back as an XML stream, That’s really where the similarity ends. Unlike SOAP, POX is very small, terse and easy to read.  For example, consider this SOAP message:

Now check out the exact same message in it’s POX version:

Wow! Three things were accomplished here. First, and most strikingly it’s a MUCH smaller message. As a result it’s become much more human-friendly. Additionally we’ve trimmed a lot of the complexity that comes with SOAP out of the process. We do need to keep in mind that the simplicity comes at a cost; when we removed the SOAPyness from our message we lost some security as well as some other WS-* abilities like addressing, routing, reliability and anything involving workflow. More on that in a bit. But what we do have is a simple XML document that can be easily understood, parsed and acted upon.

JSON

I’ve you’ve been doing “Web 2.0” stuff you’ve no doubt heard of Asynchronous JavaScript and XML, better known as AJAX. AJAX is all the rage with web developers who want to provide a good user experience on the web by making several “smaller” calls to a back-end web service and using that result to change part of the page instead of doing a full page refresh. These keeps the user from having to sit and wait for the whole page to be re-served and re-rendered when only a small part of the page is changing. Most of these calls are coming from client side JavaScript and in the “dark ages” you would get back an XML document that you would have to parse before you can use.

JavaScript Object Notation or JSON was defined in 2001, but didn’t really gain steam till 2005 when large web properties like Yahoo, Google and Microsoft embraced it. The idea was that since we’re already using JavaScript to make these calls, and JavaScript is a dynamic scripting language, why not just return the text that corresponds to a JavaScript object? This made life a lot easier for the client developers, and once libraries to quickly format messages for JSON it made life just as easy for service developers too. An example of the JSON equivalent of the previous message would look something like this:

As you can see JSON shares a lot of characteristics of POX; both are simple, compact and human readable. It’s also instantly consumable by JavaScript so there’s no need to parse it, pull it apart and put it in an object; it’s already in one. Once you get this back from your service you can use it like any other object in your client side JavaScript.

What of SOAP?

The resurgence of REST does not mean the death of SOAP. Yes, SOAP is complex. But that complexity brings power. For the Enterprise, SOAP is not going away. There are still too many things that business cares about that are easier to do in SOAP than with REST-based services. Things like transactions, reliable messaging, workflows and orchestrations, message routing and custom security. SOAP excels at these and that is why you need to know (and care) about it.

What is changing is how you architect and plan your service infrastructure. Specifically where you use SOAP/REST based services. Personally, I’ll start from the standpoint of making something a REST service until a requirement arises that can be more quickly, easily and reliably done with SOAP. Then I’ll switch to SOAP. An emerging pattern many have seen that follows this line of thinking is that we are starting to see REST services deployed along the edges of a service architecture, in places where outside client need to have easy and interoperable access to our data. While SOAP services are still very much relied on in the center of the service architecture, where things like sessions, long running workflows, more advanced security and services busses are needed. Of course the standard Architect mantra of “It depends” comes into play.

Next time we’ll use WCF to add some REST-based services to our Web Bagels application.