REST Web Services with ServiceStack

Over the past month I ventured deep into the alternative side of the .NET web world. I took quite a few web frameworks for a test drive, including OpenRasta, Nancy, Kayak and ServiceStack. All of the aforementioned supports Mono, except OpenRasta, that has it on its road-map. While kicking the tires of each framework, some harder than others, I saw the extent of just how far .NET has grown beyond its Microsoft roots, and how spoiled .NET developers have become with a long list of viable alternative .NET solutions from the valley of open source.

ServiceStack really impressed me, with its solid mix of components that speak to the heart of any modern C# web application. From Redis NOSQL and lightweight relational database libraries, right through to an extremely simple REST and SOAP web service framework. As the name suggests, it is indeed a complete stack.

Anyways, enough with the marketing fluff, let’s pop the bonnet and get our hands dirty. What I’m going to show you isn’t anything advanced. Just a few basic steps to help you to get to like the ServiceStack web framework as much as I do. You can learn the same things I’ll be explaining here by investigating the very complete ServiceStack example applications, but I thought some extra tidbits I picked up working through some of them should make life even easier for you.

Some Background Info On REST

I’m going to show you how to build a REpresentation State Transfer (REST) web service with ServiceStack. RESTful web services declare resources that have a URI and can be accessed through HTTP methods, or verbs (GET, PUT, POST and DELETE), to our domain services and entities. This is different from SOAP web services that require you to expose methods RPC style, that are ignorant of the underlying HTTP methods and headers. To implement a REST resource and its HTTP-methods in ServiceStack requires the use of two classes, RestService and RestServiceAttribute.

Another feature of REST is that data resources are encoded in either XML or JSON. However, the latest trend is to encode objects in JSON for its brevity and smaller size, rather than its more clunky counterpart, XML. We will therefore follow suit and do the same. Okay, I think you’re ready now to write your first line of ServiceStack code.

Create a Web Service Host with AppHostBase

The first thing you have to do is specify how you’d like ServiceStack to run your web services. You can choose to either run your web services from Internet Information Services (IIS) or Apache, or from the embedded HTTP listener based web server. Both of these approaches require you to declare a class that inherits from AppHostBase:

public class AppHost: AppHostBase
{
    public AppHost()
        : base("Robots Web Service: It's alive!", typeof(RobotRestResource).Assembly) {}

    public override void Configure(Container container)
    {
        SetConfig(new EndpointHostConfig
        {
            GlobalResponseHeaders =
            {
                { "Access-Control-Allow-Origin", "*" },
                { "Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS" },
            },
        });
     }
 }

Class AppHost‘s default constructor makes a call to AppHostBase‘s constructor that takes 2 arguments. This first argument is the name of the web app, and the second argument tells ServiceStack to scan the Assembly where class RobotRestResource is defined, for REST web services and resources.

AppHostBase‘s Configure method must be overridden, even if it’s empty, otherwise you’ll get and exception. If you plan on making cross domain JavaScript calls from your web user interface (i.e. your web interface is written in JavaScript and hosted on a separate web site from your web services) to your REST resources, then adding the correct global response headers are very important. Together the two Access-Control-Allow headers tell browsers that do a pre-fetch OPTIONS request that their cross domain request will be allowed. I’m not going to explain the internals, but any Google search on this topic should yield sufficient info.

Now all that’s left to do is to initialize your custom web service host in Global.asax‘s Application_Start method:

public class Global : System.Web.HttpApplication
{
    protected void Application_Start(object sender, EventArgs e)
    {
        new AppHost().Init();
    }
}

The last thing you might be wondering about, before we move on, is the web.config of your ServiceStack web service. For reasons of brevity I’m not going to cover this, but please download ServiceStack’s examples and use one of their web.configs. The setup require to run ServiceStack from IIS is really minimal, and very easy to configure.

Define REST Resources with RestService

Now that we’ve created a host for our services, we’re ready to create some REST resources. In a very basic sense you could say a REST resource is like a Data Transfer Object (DTO) that provides a suitable external representation of your domain. Let’s create a resource that represents a robot:

using System.Collections.Generic;
using System.Runtime.Serialization;

[RestService("/robot", "GET,POST,PUT,OPTIONS")]
[DataContract]
public class RobotRestResource
{
[DataMember]
public string Name { get; set; }

[DataMember]
public double IntelligenceRating { get; set; }

[DataMember]
public bool IsATerminator { get; set; }

[DataMember]
public IList<string> Predecessors { get; set; }

public IList<Thought> Thoughts { get; set; }

}

The minimum requirement for a class to be recognized as a REST resource by ServiceStack, is that it must inherit from IRestResource, and have a RestServiceAttribute with a URL template, and that’s it. ServiceStack doesn’t force you to use the DataContractAttribute or DataMemberAttribute. The only reason I used it for the example is to demonstrate how to exclude a member from being serialized to JSON when it’s sent to the client. The Thoughts member will not be serialized and the web client will never know the value of this object. I had a situation where I wanted to have a member  on my resource for internal use in my application, but I didn’t want to send it to clients over the web service. In this situation you have to apply the DataContractAttribute to your resource’s class definition, and the DataMemberAttribute to each property you want to expose. And that’s it, nothing else is required to declare a REST resource ffor ServiceStack.

Provide a Service for Each Resource with RestServiceBase

Each resource you declare requires a corresponding service that implements the supported HTTP verb-methods:


public class RobotRestService: RestServiceBase<RobotRestResource>
{
    public override object OnPut(RobotRestResource robotRestResource)
    {
        // Do something here & return a
        // new RobotRestResource here,
        // or any other serializable
        // object, if you like.
    }

    public override object OnGet(RobotRestResource robotRestResource)
    {
        // Do some things here ...
        // Return the list of RobotRestResources
        // here, or any other serializable
        // object, if you like.

        return new []
        {
            new RobotRestResource(),
            new RobotRestResource()
        };
    }
}

In order for ServiceStack to assign a class as a service for a resource, you have to inherit from RestServiceBase,  specifying the resource class as the generic type. RestServiceBase provides virtual methods for each REST approved HTTP-verb: OnGet for GET, OnPut for PUT, OnPost for POST and OnDelete for DELETE. You can selectively override each one that your resource supports.

Each HTTP-verb method may return one of the following results:

  1. Your IRestResource DTO object. This will send the object to the client in the specified format JSON, or XML.
  2. ServiceStack.Common.Web.HtmlResult, when you want to render the page on the server and send that to the client.
  3. ServiceStack.Common.Web.HttpResult, when you want to send a HTTP status to the client, for instance to redirect the client:
    var httpResult = new HttpResult(new object(), null, HttpStatusCode.Redirect);
    httpResult.Headers[HttpHeaders.Location] = "https://openlandscape.wordpress.com";
    return httpResult;
    

And that’s it. Launch your web site, and call the OnGet methof at /robot?format=json, or if you prefer XML /robot?format=xml. To debug your RESTful service API I can highly recommend the Poster Firefox plug-in. Poster allows you to manually construct HTTP commands and send them to the server.

You might be wondering what the purpose is of RobotRestResource that gets passed to each HTTP-verb method. Well, that is basically an aggregation of the posted form parameters and URL query string parameters. In other words if the submitted form has a corresponding field name to one of RobotRestResource’s properties, ServiceStack will automatically assign the parameter’s value to the supplied RobotRestResource. The same applies for query strings, the query strings ?Name=”TheTerminator”&IsATerminator=true: robotRestResource’s Name will be assigned the value of “TheTerminator” and IsATerminator will be true.

Using ServiceStack’s Built-In Web Service as a Service Host

The above discussion assumed that you’ll be hosting your ServiceStack service in IIS or with mod_mono in Apache. However, ServiceStack has another pretty cool option available, self hosting. That’s right, services can be independently hosted on their own and embedded in your application. This might be useful in scenarios where you don’t want to be dependent on IIS. I imagine something like a Windows service, or similar, that also serves as small web server to expose a web service API to clients, without the need for lengthy and complicated IIS setup procedures.

var appHost = new AppHost();
appHost.Init();
appHost.Start("http://localhost:82/");

To start the self hosted ServiceStack you configure your host as usual, and then call Start(…), passing the URL (with free port) where the web server will be accessed.

Why Use ServiceStack

For me one of the big reasons for choosing ServiceStack is that it has a solid library to build web services running on Mono. However, after using if for a while I found its easy setup and simple conventions very refreshing from the often confusing and cumbersome configuration of Windows Communication Foundation (WCF) web services.ServiceStack also does a much better job of RESTful services, than WCF’s current implementation. I know future versions of WCF will enable a more mature RESTful architecture, but for now it’s pretty much RPC hacked into REST. Another bonus was the complete set of example apps that were a great help to quickly get things working. So if you’re tired of WCF’s heavy configuration and you’re looking for something to quickly implement mature RESTful web services, then definitely give ServiceStack a try.


Call SOAP-XML Web Services With jQuery Ajax

jQuery: Write less, do more

jQuery: Write less, do more

jQuery‘s popularity has really exploded over last few years. What really stands out about jQuery is its clear and consise JavaScript library. Other things I’ve come to appreciate over time is its deep functionality and completely non-intrusive configuration. Recently, to improve the responsiveness of my user interfaces, I decided to use jQuery’s Ajax to call SOAP-XML web services directly. I struggled to find good information on how this can be done. There are a lot of good examples on the web that demonstrate how to use JSON web services from jQuery Ajax, but almost none for SOAP-XML web services.

.NET Web Service Operation Definition

.NET Web Service Operation Definition

Before you can call the web service from client script you need to obtain the web service operation’s WSDL. If you’re using a .NET web service, you can just point your browser to the web service’s URL, and click on the operation’s name.

The example web service operation I’m using, SaveProduct, has the following schema:

POST /ProductService.asmx HTTP/1.1
Host: localhost
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://sh.inobido.com/SaveProduct"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<SaveProduct xmlns="http://sh.inobido.com/">
<productID>int</productID>
<productName>string</productName>
<manufactureDate>dateTime</manufactureDate>
</SaveProduct>
</soap:Body>
</soap:Envelope>

The method that will contact this operation looks like this:

var productServiceUrl = 'http://localhost:57299/ProductService.asmx?op=SaveProduct'; // Preferably write this out from server side

function beginSaveProduct(productID, productName, manufactureDate)
{
var soapMessage =
'<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> \
<soap:Body> \
<SaveProduct xmlns="http://sh.inobido.com/"> \
<productID>' + productID + '</productID> \
<productName>' + productName + '</productName> \
<manufactureDate>' + manufactureDate + '</manufactureDate> \
</SaveProduct> \
</soap:Body> \
</soap:Envelope>';

$.ajax({
url: productServiceUrl,
type: "POST",
dataType: "xml",
data: soapMessage,
complete: endSaveProduct,
contentType: "text/xml; charset=\"utf-8\""
});

return false;
}

function endSaveProduct(xmlHttpRequest, status)
{
 $(xmlHttpRequest.responseXML)
    .find('SaveProductResult')
    .each(function()
 {
   var name = $(this).find('Name').text();
 });
}

In order to call the web service, we need to supply an XML message that match the operation definition specified by the web service’s WSDL. With the operation’s schema already in hand, all that is required is to exchange the type names for the operation’s paramaters, with their actual values. The variable soapMessage contains the complete XML message that we’re going to send to the web service.

To make an Ajax request with jQuery you use the ajax method found on the jQuery object. The $/dollar sign is an alias for jQuery, the actual name of the object; the symbol just provides a shortcut to the jQuery object. The ajax method provides a wide range of options to manage low level Ajax tasks, but we’ll only cover the ones we’ve used here:

  1. url: Should be pretty obvious. This is the web service’s end-point URL. All I’ve done is instead of hard coding it, I assigned the URL to the variable productServiceUrl when I create the page’s HTML from the server side.
  2. type: The type of request we’re sending. jQuery uses “GET” by default. If you quickly take a look again at the SaveProduct operation’s definition, you will notice that on the 1st line it specifies that requests should use the “POST” HTTP method.
  3. dataType: The type of data that the response will send back. The usual types are available like html, json, etc. If you’re working with a SOAP web service, you need to specify the xml dataType.
  4. data: Another easy one. This is the actual data, as XML text, you will be sending to the web service.
  5. complete: The callback delegate that will be executed when the request completes. The callback method must implement the following signature: function (XMLHttpRequest, textStatus) {  /* Code goes here */ } .
  6. contentType: A string representing the MIME content type of the request, in this case it’s “text/xml” because we’re working with a SOAP web service that expects XML data.

Now you’re ready to send your XML data off to the web service. Once the server finishes processing the request, the endSaveProduct method gets called. To process the XML response in jQuery, you need to know the SOAP reponse’s schema/definition. The SaveProduct web method has the following schema:

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <SaveProductResponse xmlns="http://sh.inobido.com/">
      <SaveProductResult>
        <ID>int</ID>
        <Name>string</Name>
        <ManufactureDate>dateTime</ManufactureDate>
      </SaveProductResult>
    </SaveProductResponse>
  </soap:Body>
</soap:Envelope>

From this schema it should be clear that the web method SaveProduct sends back the Product object that was saved. You will find the XML document/data on the xmlHttpRequest parameter’s responseXML property. From here you can use the usual jQuery methods to traverse the XML document’s nodes to extract the data.


Web Service HTTP-407 Proxy Access Denied Error

Summary
When calling a web service operation you get the following error: “The request failed with HTTP status 407: Proxy Access Denied.”Conditions:

  1. When you inspect System.Security.Principal.WindowsIdentity.GetCurrent() the returned WindowIdentity is the current user’s Windows account.
  2. The web service proxy’s Proxy is null: “webService.Proxy == null” I true.
  3. The web service’s Credentials might be set or not. You get the above error even though you’ve set the web service proxy’s Credentials from System.Net.CredentialCache.DefaultCredentials: “webService.Credentials = System.Net.CredentialCache.DefaultCredentials”.

Solution
If the web service proxy’s Proxy property is null, then assign the default WebProxy to it:

if ( webService.Proxy == null )
{
webService.Proxy = System.Net.WebProxy.GetDefaultProxy();
webService.Proxy.Credentials = System.Net.CredentialCache.DefaultCredentials;
}