WCF REST: XML, JSON or Both?

WCF (Windows Communication Foundation) is the new standard for building services with .NET and REST (REpresentational State Transfer) has been a very popular technique when building services and not just in the .NET space. With services, you transport serialized data across the pipe to be worked with and there are a few serialization methods:

• Binary: Not for REST services, but provides the smallest packet size.  Each end must explicity know how to handle the data.
• SOAP: The long running standard for web services.  Very descriptive, but a very large packet size due to the amount of meta data.
• XML (POX): Plain Old XML provides the just the data with structure without the meta data leaving a smaller packet size.
• JSON (JavaScript Object Notation): A new and up coming standard with a similar packet size to a plain XML feed, but can be used directly in JavaScript making it the best option when consuming a service from jQuery.

My preferred serialization method is either XML or JSON, with a strong leaning towards JSON.  There are however many instances where I may want a service call to respond with either.  I may also want to pass data to the same service in either XML or JSON.  Luckily, with WCF, you can write a service that can both accept and receive either without you having to write multiple methods by using the accept and content-type HTTP headers.

When building a service in WCF, there are a few things you will need to do to get a RESTful feel.  First, you need to make sure your class has the annotation to allow for ASP.NET compatibility:

[AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Allowed)]public class MyService

This is to allow the service to respond through and ASP.NET application.  Secondly, you will want to use the new routing features of ASP.NET 4 to build a REST friendly url:

RouteTable.Routes.Add(new ServiceRoute("myservice", new WebServiceHostFactory(), typeof(MyService)));

And finally, you will need to annotate the web method:

[WebInvoke(UriTemplate = "dostuff", Method = "POST", BodyStyle = WebMessageBodyStyle.Bare)]public StuffResponse DoStuff(RequestStuff requestStuff)

The combination of the route addition and the WebInvoke UriTemplate will allow you to call your method by sending an HTTP POST to /myservice/dostuff.  The RequestStuff class is any class that you want to be able to pass in.  As long as the structure of the XML or JSON matches the class structure, .NET will serialize it for you.  In this method we are setting the HTTP method to POST, but you can use any of the other REST verbs here as well.

The trick to getting the method to respond with and to either XML or JSON is all in the request headers.  To tell the service you want to work with XML, set both the HTTP Accept and Content-Type headers to "application/xml".  Then if you post XML, it will be deserialized and the return object will be serialized into XML.  If you want JSON, set both to "application/json".  There are several JSON content-type options I have seen out there, but I have only had luck with "application/json" when working with .NET.  You can also send JSON and get back XML by setting the Content-Type to "application/json" and the accept to "application/xml", but I would imagine that you would only work with one type.

The beauty of this method is that you don't have to write multiple service methods to respond to the serialization type.  Also since you are building the service in this manner, it is accessible from clients that are not .NET based and still keep a relatively small packet size.