I recently made two contributions to the Agatha Project by Davy Brion over on Google Code, and one of the things I wanted to follow up with was a post showing examples and some, seemingly required tid bits. The contributions which I made where:
- To support StructureMap
- To include REST (JSON and XML) support for the service contract
The examples which I have made, I want to format them so they fit in with the current format of examples over on Agatha and hopefully create and submit a third patch which will include these examples to help others who wish to use these additions.
Whilst building these examples for both XML and JSON I have learnt a couple of things which I feel are not really well documented, but are extremely good practice and once known make perfect sense. I have chosen a real basic e-commerce context for my example Requests and Responses, and have also made use of the excellent tool AutoMapper, again on Google Code.
Setting the scene
I have followed the Pipes and Filters Pattern with the IQueryable interface on my Repository and exposed the following methods to query Products:
IQueryable<Product> GetProducts();
IQueryable<Product> ByCategoryName(this IQueryable<Product> products, string categoryName)
Product ByProductCode(this IQueryable<Product> products, String productCode)
I have an interface for the IProductRepository but for the concrete implementation I have simply created a protected getter which populates a private List<Product> with 100 test products with random data. Another good reason for following an interface based approach is that it will demonstrate usage of my first contribution which is the StructureMap support. Finally the two Domain Objects I have made are Product and Category as shown below:
public class Product
{
public String ProductCode { get; set; }
public String Name { get; set; }
public Decimal Price { get; set; }
public Decimal Rrp { get; set; }
public Category Category { get; set; }
}
public class Category
{
public String Name { get; set; }
}
Requirements for the REST Support
One of the things which you will notice with Agatha is that you do not have to decorate your Request and Response objects with the WCF Service Model Attributes like DataContract, DataMember etc… Unfortunately from what I have seen, these are required if you want the same types to work with your REST endpoint. I have not tried but I assume the same result can be achieved by simply decorating the same classes with the Serializable Attribute. Without this the operation will fail.
Another surprising thing I have found is that it did not work until I used the following Attribute parameters:
e.g.
[DataContract(Name = "GetProductsRequest", Namespace = "AgathaRestExample.Service.Requests")]
public class GetProductsRequest : Request
{
}
Although I was surprised by this, things kind of explained themselves when I got round to figuring out the exact construct required for both the XML and the REST. One of the things which you already know and are then reminded of is that each of your Requests and Responses ultimately inherit from an abstract base class respectively. This information needs to be represented in a way native to the format being used. I have seen this in XML but I have not seen the format which is required for the JSON.
JSON Consumer Example
I have used JQuery to create the example and I simply want to make two requests to the server which as you will know with Agatha are transmitted inside an array to reduce the service calls. I have also used a tool called json2 which is again over at Google Code simply to convert my JSON expression into its string format for transmission. You will notice that I specify the type of Request I am using and the relevant Namespace it belongs to. Also notice that the second request has a parameter so each of these two object are representing an abstract Request and the parameters of the object describe it.
<script type="text/javascript">
var bodyContent = $.ajax({
url: "http://localhost:50348/service.svc/json/processjsonrequests",
global: false,
contentType: "application/json; charset=utf-8",
type: "POST",
processData: true,
data: JSON.stringify([
{ __type: "GetProductsRequest:AgathaRestExample.Service.Requests" },
{ __type: "GetProductsByCategoryRequest:AgathaRestExample.Service.Requests", CategoryName: "Category1" }
]),
dataType: "json",
success: function(msg) {
alert(msg);
}
}).responseText;
</script>
XML Consumer Example
For the XML Consumer example I have chosen to use a simple Console Application and make a WebRequest to the service using the XML as a request. I have made a crude static method which simply reads from an XML File, replaces some value with a parameter and returns the formatted XML. I say crude but it simply shows how XML Templates for each type of Request could be made and then have a wrapper utility in whatever language you use to combine the requests which are required. The following XML is the same Request array as shown above but simply in the XML Format.
<?xml version="1.0" encoding="utf-8" ?>
<ArrayOfRequest xmlns="http://schemas.datacontract.org/2004/07/Agatha.Common" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Request i:type="a:GetProductsRequest" xmlns:a="AgathaRestExample.Service.Requests"/>
<Request i:type="a:GetProductsByCategoryRequest" xmlns:a="AgathaRestExample.Service.Requests">
<a:CategoryName>{CategoryName}</a:CategoryName>
</Request>
</ArrayOfRequest>
It is funny because I remember submitting a question to StackOverflow asking whether there was a REST Client Generation tool similar to what Microsoft used for their RestStarterKit but which could be applied to existing services which have REST endpoints attached. I could not find any but this is now definitely something which I am going to build, as I think it is extremely useful to have but also it should not be too difficult based on the information I now know about the above. Finally I thought that the Strategy Pattern would lend itself really well to this type of thing so it can accommodate for different languages.
I think that is about it, I have included the code for the example Console app which I made below incase anyone wants to have a mooch at the code. As I said above I want to reformat these to fit in with the current examples over on the Agatha project, but also now thinking about it, make a Documentation Web method…{brain ticking} :-)
Cheers for now and here is the final bit of code:
static void Main(string[] args)
{
var request = WebRequest.Create("http://localhost:50348/service.svc/xml/processxmlrequests");
request.Method = "POST";
request.ContentType = "text/xml";
using(var writer = new StreamWriter(request.GetRequestStream()))
{
writer.WriteLine(GetExampleRequestsString("Category1"));
}
var response = request.GetResponse();
using(var reader = new StreamReader(response.GetResponseStream()))
{
Console.WriteLine(reader.ReadToEnd());
}
Console.ReadLine();
}
static string GetExampleRequestsString(string categoryName)
{
var data = File.ReadAllText(Path.Combine(Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location), "ExampleRequests.xml"));
data = data.Replace("{CategoryName}", categoryName);
return data;
}
}