Table of Contents for this Series 

The terminology, protocols, and technical relationships surrounding Microsoft data access and service technologies do not lend themselves well to cursory descriptions. So my intent here is to provide some additional context regarding REST and SharePoint 2010’s relationship with the larger world of Microsoft’s data access and service technologies. 

I begin with Windows Communication Foundation (WCF) – WCF encapsulates the essential service plumbing required of modern service based applications. WCF covers a lot of ground by keeping up with standards and adapting to new conventions while still maintaining a good development experience.

See  http://msdn.microsoft.com/en-us/netframework/aa663324.aspx

However, a few important aspects of using services, in general, have not been fully realized. I’ll use SOAP as my example (as the .NET Rocks show did). I’m not picking on SOAP services specifically, but SOAP is useful for illustrating the points made here.   

• Although SOAP is XML based and very mature its also complex and difficult to consume by certain client technologies. It often requires tooling support and careful attention to configuration, among other things. Try calling a modestly complex .NET SOAP service from ECMAScript without library support, or Java for that matter. Improvements have been made and SOAP is a solid technology usable as part of architectural designs based on use cases that require ws-* standards. I don’t expect it will be going away anytime soon. Plus tooling support within Visual Studio is unmatched in capability.
• Services have largely been used as remote procedure calls (methods/functions/operations) – this style of use is fine but has drawbacks:
  1. You’re probably not going to model your service call very well against business/data entities – the further along you are in a projects timeline the greater chance the method calls you define are more tactical in nature rather than adhering to a strategic direction. In this case your service calls have funny names and a bunch of parameters that cover the edge cases and a few squeaky wheels. Refactoring is your way to minimize this pain.
  2. Documentation starts becoming difficult – try and remember what that fourth parameter was for the method InsertEggByType(…). Then ask yourself why inserting that egg was required anyways. 
  3. Clients are computers too and much of the processing need not be hidden on the server. So the need for a rich set of parameter and service names may be just unnecessary clutter. The Keep It Simple Simon (KISS) principle minimizes this pain. 
  4. Interoperability can be dismal – no agreement for how the basic CRUD operations are named, behave, or report errors on any given entity exists. This means you supply a WSDL and expect the client to create proxy objects and handle the idiosyncrasies of the call – all under the covers.   

The essential takeaway from above is that “signal to noise ratio” can be worse with operation-based service calls like SOAP. Again, because function names and parameters proliferate with less control. Now, spinning forward a bit, the last few years have witnessed the rise of REST as a useful services construct.

REST’s architectural style can be applied to various communication protocols such as HTTP but a key point is that REST IS NOT HTTP. However, REST PLUS HTTP can be thought of as being The Web as we know it today. REST itself makes extensive use of HTTP verbs. Specifically, REST places certain constraints on how the HTTP protocol is used and provides for Create, Read, Update, and Delete (CRUD) operations via HTTP POST, GET, PUT, and DELETE.

One immediate benefit of REST is “protocol uniformity” for any service call with regard to basic CRUD operations. To put this another way – REST allows us to fully exploit The Web’s basic design pattern directly. That is, every service created using the REST style understands how CRUD operates. 

REST is not enough – REST does not care about payloads. A REST service using GET could just as easily pull back ASCII text from a server as it can plain old XML (POX), or even some highly specific XML you conjure up.

Because REST based communications can agree on the basic CRUD machinery a good next step would be to agree on what REST actually transfers. This would further narrow the gap with regard to systems interoperability. As such, Microsoft has adopted the use of AtomPub (and JSON) as content types sent over the wire.

REST + AtomPub is not enough – AtomPub puts us on the correct course but ultimately does not care what data is contained within the fields themselves. A REST service using AtomPub could represent any messy set of data . This still makes it difficult for clients to treat AtomPub with uniformity. By uniform, I mean understanding and agreeing that it represents some entity. However, AtomPub is less of a problem because disparate systems can agree to understand AtomPub over REST as the payload.

One way to improve the situation is to “model your service” in a similar way that you would model, say, using ORM to map objects to a database (perhaps a bad example) – this means a REST call can pull back an AtomPub representation of you business entity. This is often referred to as a resource style of service. For example, a classroom can be obtained by calling http://www.classroomtocomputer.com/classroom where the AtomPub format returns the fields that constitute the “classroom” entity.

REST + AtomPub + Modeling is not enough – Modeling your service call provides the essential mapping of your server side business logic but offers very little beyond basic CRUD and understanding the payload – of course, this is less of a problem because you know (by knowing your resource – “classroom”) how to pull back the model. The interoperability gap narrows a bit further.   

So what’s missing? The common things any client needs to manipulate a model such as collections, filtering, or relating one entity to another. SOAP would have you create methods for the various cases that deal with things such as filtering, for example. That’s not good because it means almost any service your write now is really just another implementation of the same pattern that really should be available by default.

Because we are talking about REST based services this becomes a great opportunity to add URI semantics that provide the common behaviors you would use on any entity in your application. So making this happen within the context of a REST interface promotes consistency provided everyone can agree on the semantics. A good place to start is by extending the AtomPub protocol with URI semantics. See [MC-APDSU]: Atom Publishing Protocol: Data Services URI and Payload Extensions. A short list of examples include $filter, $orderby, $expand, $skip, $top, etc, etc. This is the oData protocol.

The Open Data Protocol (oData) is really REST + AtomPub + Modeling + URI Semantics. See – http://www.odata.org/ This is a great concept and Microsoft has done a really good job in this regard, but we can also thank Pablo Castro for moving these ideas forward. See http://blogs.msdn.com/pablo/

Finally, I’ll tie this all together with regard to SharePoint 2010 – WCF is now deeply embedded as a companion technology within SharePoint 2010 and WCF now exposes the oData protocol (as REST services). SharePoint 2010 uses WCF and specifically uses ListData.svc to provide oData style access into lists and libraries from any system capable of understanding and consuming the protocol – listen to .NET Rocks show 519 for further insight on this topic

This Quick Start Guide (now several posts) explores the capability of REST services from within SharePoint 2010 using ECMAScript as the sample client technology. 

Cheers!