Rest Service Implementation

WCF Rest-like Service

Proto-type implementation

Vocabulary

Representational State Transfer:  Low level stateless software architecture approach that uses the structure of URI's (uniform resource locator) and HTTP 1.0 verbs to define resultant service data displays. REST outlines how to define, access and address data sources without the need for additional messaging layers or session tracking.

Windows Communication Foundation: WCF is a platform that supports a multitude of different methods to expose data services, in a service-oriented methodology. It is request agnostic, meaning it is not tied to a single request method like REST, or SOAP.

Http Client: Object to initiate a Http Request, previously known as XHR or XMLHttpRequest. This safe for scripting object was used to initiate AJAX calls.

Document

This document is meant to detail the top level technological decisions that were made in the proto-type WCF Rest-like Service implementation. This document, based on proto-type implementation is meant to postulate possible guidelines, as such this document will remain in draft format in perpetuity, and will be superseded by any and all Guidance Documents or White Pages on the technologies in this document.

References - Prerequisites

●      WCF Rest Service Template 4.0 for Visual Basic

●      WCF Rest Starter Kit (http client)

●      Visual Studios 2010, .Net Framework 4.0

●      IIS 7.0

Http Verbs

It seems appropriate to start any discussion of restful(like) solutions with a conversation about HTTP Request Methods. These are often referred to as "verbs."  Most of us are familiar with "Get" and "Post" but have failed up to now to notice the other request methods that the http protocol supports. For now, let it be sufficient (until we begin our discussion on routing masks) to say that restful services respond to not only the URI of a request, but also route based on the action that is described via the Request Method. WCF commonly responds to GET, POST, PUT and DELETE for crud operations, there are more Verbs in the HTTP Protocol Specification, but they are not in common usage in Restful services.

Routes

Guideline: Configure your routes in the virtual route table, accessed in code in the Global.asax file in a custom Procedure called RegisterRoutes.  This behavior is similar to the routing mechanism employed by MVC.Net web sites.

fig. 1

Private Sub Application_Start(ByVal sender As Object, ByVal e As EventArgs)

  RegisterRoutes()

End Sub

Private Sub RegisterRoutes()

  RouteTable.Routes.Add(New ServiceRoute("RouteName", New WebServiceHostFactory(), GetType(MyApplication.MyClass)))

End Sub

Application Start

Creating a response to a request in a virtual location (there is no physical file to respond to the request), means that a listener will have to be created.  WCF supplies a factory method to create this listener, with the WebServiceHostFactory class. This factory class should be called at application start,  and added as a Route to the application's RouteTable object.

fig. 2

RouteTable.Routes.Add(New ServiceRoute("RouteName", New WebServiceHostFactory(), GetType(MyApplication.MyClass)))

Routing

Incoming request are passed from IIS to the WebServiceHostFactory, where they are routed according to the RouteTable rules into the class specified in the Routes.Add type argument. The request is then picked up by the Class, and is handled by a method of the class based on the "verbs" and the arguments specified by the request.

 

Route Masks, (HTTP Method and UriTemplates)

The WCF Rest Template offers Common Routing, and templates for the most common scenerios. These are mostly self defining, based on the HTTP method, and also the existance of an id or name argument. It is worth noting, that all arguments passed via a URI will be of type string.

fig. 3

      <WebGet(UriTemplate := "")>

        Public Function GetCollection() As List(Of SampleItem)

            Throw New NotImplementedException()

        End Function

       

        <WebInvoke(UriTemplate := "", Method := "POST")>

        Public Function Create(ByVal instance As SampleItem) As SampleItem

            Throw New NotImplementedException()

        End Function

       

        <WebGet(UriTemplate := "{id}")>

        Public Function [Get](ByVal id As String) As SampleItem

            Throw New NotImplementedException()

        End Function

       

        <WebInvoke(UriTemplate := "{id}", Method := "PUT")>

        Public Function Update(ByVal id As String, ByVal instance As SampleItem) As SampleItem

            Throw New NotImplementedException()

        End Function

       

        <WebInvoke(UriTemplate := "{id}", Method := "DELETE")>

        Public Sub Delete(ByVal id As String)

            Throw New NotImplementedException()

        End Sub

 

Restful services have some common practices, which govern there usage, and these should be adhered to as long as they do not create odiously architected solutions. There is an expectation that reaching the root a Restful Object (in a URL Get), that object will return an unfiltered list of objects of that type.  When an "id" or "name" is specified in a Get on a Restful Object then the expectation is that the Restful Service will return a single instance of the item in question.  Using the HTTP Method, "Delete" means that the requesting caller would like to see that item removed from the underling persistence store.  This is clear, but the Delete could be requested using either a "id" as in "please remove the item with this id from the persistence store" or the object could be sent in a http form, meaning "please remove the item in the persistence store that resembles this item." The Put and Post methods have similar problems, as the user community is not 100% decided on a usage for these items. For the purposes of our discussion, we will assume that POST is equal to a form post in which the requestor desires that we insert the item into the persistence store, and that a PUT is when the requestor desires us to perform an update on an item in the persistence store.

            A Note of Caution: It is incumbent on me to offer a note of caution on POST and PUT, the   Restful service creator should handle PUTs in POSTs and POSTs in PUTs, or send back an    explanation on why the desired result was not achieved.

Complex Routes

Routes that specify multiple filtering items at different levels of the Restful Portion of the Resource Locator, are complex routes.

Complex routes need to be specified on the top hierarchical level. For instance, there is a parent-child relationship and the service should list a collection of children, filtered by the parent id, then the handler method will be created on the parent level.

fig. 4

      <WebGet(UriTemplate := "{id}/Child")>

        Public Function GetChildCollection() As List(Of SampleItem)

            Throw New NotImplementedException()

        End Function

       

Introducing the HtHttpClient

The WCF Rest starter kit comes with a new and improved HttpClient Utility. This new client, like the old XMLHttpRequest Utility allows a thread to programmatically access the web resources without the overhead of a user-interface. The new HttpClient is a major update of functionality, since the XHR methodologies of early 2000 contained no support for Http Request Methods beyond GET and POST and also were not concerned about serialization. Modern Service Architectures have significant enhancements to serialization and do not stop at POX (Plain Old XML, simply returning a document of XML data). The WCF service and the HttpClient come together in serialization of strongly typed data, you may expose your data from the WCF as "exact type" and consume it in your interface as the same "exact type" that you exposed it as. This methodology means that a WSDL data contract is not only unnecessary, but also undesirable, in so far as the WSDL creates a new type that the client consumes.

Additionally the new HttpClient has built in support for "DELETE" and "PUT" Http Verbs, as well as the more common, "GET" and "POST" of XHR.

Usage

The HttpClient is located in the Microsoft.Http.dll, which is included in the WCF Rest Starter Kit. Adding Headers is simple in the

 fig. 5

        Using client As New HttpClient("http://localhost:8080/Route/")

            Using response As HttpResponseMessage = client.[Get]("Action?id=3")

                response.EnsureStatusIsSuccessful()

                Dim anon = response.Content.ReadAsDataContract(Of List(Of ContractLibrary.Interfaces.IItem))()

            End Using

        End Using

Custom Headers

Adding Headers is simple in the HttpClient. Access the DefaultHeaders Collection of your instantiated client and then call the Add method.

fig. 6

        client.DefaultHeaders.Add("CustomHeader", HeaderValue)

Security/Authentication

The Restful service site is secured through the usual Microsoft Web Security Provider, and needs no configuration beyond what is usually contained in a .net web site. Accessing the resources in a secure manner usually means that you will be sending a set of credentials (as system.net.icredentials) in the Http Request of the HttpClient Utility.

fig. 7

        client.TransportSettings.Credentials = Credentials

Configuration

The options specified in the web.config file of the Rest service are fairly straight forward.  Though please note the last WCF section, and in particular the attribute HelpEnabled, which automatically creates an operation description page for each route when the route action is "/help."

Authentication:

    <roleManager defaultProvider=".." enabled="true">

      <providers>

        <add name=".." connectionStringName=".." applicationName=".." type="System.Web.Security.SqlRoleProvider, .."/>

      providers>

    roleManager>

    <authorization>

      <deny users="?" />

    authorization>

Routing :

    <modules runAllManagedModulesForAllRequests="true">

      <add name="UrlRoutingModule" type="System.Web.Routing.UrlRoutingModule, System.Web, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" />

    modules>

WCF:

  <system.serviceModel>

    <serviceHostingEnvironment aspNetCompatibilityEnabled="true">

     

    serviceHostingEnvironment>

    <standardEndpoints>

      <webHttpEndpoint>

        <standardEndpoint name="" helpEnabled="true" automaticFormatSelectionEnabled="true"/>

      webHttpEndpoint>

    standardEndpoints>

  system.serviceModel>

REST: http://en.wikipedia.org/wiki/Restful

WCF Rest HttpClient: http://weblogs.asp.net/cibrax/archive/2009/03/13/httpclient-in-the-wcf-rest-starter-kit-preview-2.aspx

WCF Rest Template: http://visualstudiogallery.msdn.microsoft.com/e1ec66f1-902f-4e31-8227-3a537f45afa8

Http verbs: http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods

HttpClient:http://blogs.msdn.com/b/endpoint/archive/2010/01/11/clients-and-the-automatic-help-page-in-wcf-webhttp-services.aspx

Restful WCF

I had a quick write up of WCF services in a restful state.

https://docs.google.com/viewer?a=v&pid=explorer&chrome=true&srcid=0B1AwLfyKxW00MzNjODE2ZjEtMGNhMy00M2Y5LWEzMWEtODMyOTBhNmZlY2Iz&hl=en

Microsoft - A Story of an early Compiler Company

Long ago, back in the early nineteen eighties, there once was a new technology company that built compilers, this company managed to build a compiler that had one trait that was better then all the others, it had a superior implementation of a floating point operator that allowed it do better precision math then the other off the shelf compilers. Since this was good, lots of people used it.

A big company with deep pockets asked the company that was good at making compilers to build a simple text operating system for it, and so the compiler company built DOS for deep pockets. This arrangement worked out so well for both of them, they formed a short lived partnership to make a graphical operating system together.

At about the time that the first graphical operating systems from this partnership (someplace in the very early nineteen nineties) came to market, the compiler company wanted graphical applications to run on its new operating system, and so started to port some standard office productivity tools from the text based world to the new graphical operating system world. Office productivity tools had become fairly standard already, so they began making a word processor (the text based standard was word perfect) to work in their new glossy graphical computer interface. So they made Microsoft Word and in doing so created a Macro Language (based on their “Embedded Basic Language” that they created for reuse in various Applications) called WordBASIC to allow the Users of the word processor to automate tasks (after all this was a compiler company).

The compiler company then used the WordBASIC macro language foundation it had built, and ported this to a “full” compiler called VisualBasic. This new compiler had a new idea in it, to support drop and drag “Visual” development, and so the compiler company partnered with a small start-up company that made a “form generator” and incorporated the visual form generator into the final compiler. This new compiler had menus that were trivially easy to make, differentiating it with the thousands of lines of code required to handle menuing usually, so this compiler was used to make millions of applications, because it’s menu system was so easy.

It seems to me, that the softies that invented VisualBasic, had little intention of its use becoming so predominate, but that the predominants of the VisualBasic language came from its menuing system being so easy to use.

So around 1993, a set of technologies was beginning to form around Microsoft. Their DOS and IBM partnership had born fruit in the form of a new graphical operating system called windows and was shipping as Windows 3.1 which had network support. They had partnered with an innovative database company and ported the UNIX Sybase database engine to their 16 bit environment, and in the process were learning all sorts of interesting things about Client-Server development which led to the development of protocols that eased task of connecting to a remote database resource called respectively ODBC and DAO (which eventually became ADO and ADO.Net, after passing through a transitional period known as RDO).

The compiler company now had a network capable operating system, a full set of Office Productivity Tools (with embedded macro languages), a couple of decent database engines for storing data, a new “open” protocol for accessing data in databases, and a compiler that made it fairly easy to build forms that connected from from the client computer to databases, and other external resources. This setup, even though no individual tool was better or more innovative then other applications on the markup, taken together made the lives of business people easier.

The total was so much greater then the sum of the parts in fact that millions of custom applications were made for that platform by a widely divergent groups of individuals with widely varying skill sets.

This is one of the great plateaus of Information Systems, as this configuration has remained largely intact to the present, and looks capable of continue to stay in roughly this same configuration in the business world for decades.

The Innovation of Sharing

Social Network, a disruptive new innovation, is starting to shift people’s online behavior, even to the point that the meaning of "online" has even shifted from web based to mobile based.

The new world wide web will be not only based in mobile, but it will be built with applications and tools that put both people and peoples associations at the center of all activities.

Instead of content, you will have posts, and those posts will be "points of sharing", and that interplay between points of contact, "nodes" will create social network "ties."

Facebook is without doubt not only the market leader as the most used Social networking site, but also is the leader in crafting a platform and set of tools to take advantage of the new opportunities on offer in this new ecosystem.

This has rather large implications for builders of internet tools (previously web sites) and for anyone engaging in commerce on the web. The way people desire to interact with commercial offerings is changing.

Sun Microsystems - Goodbye and thanks for all the UNIX

Sun Microsystems is no more, having been purchased by a company (Oracle) that seems intent on capturing "open" software and hijacking that software for short-term gain. Certain aspects of the Oracle deal just point to Oracles acquisition of first InnoDB (the storage engine that MySQL uses) and then MySQL itself with the acquisition of Sun Microsystems, as a method to hijack the MySQL open source project.

But Sun’s founders, were amongst the creators of FreeBSD (through Bill Joy’s work on BSD UNIX), and Sun was always the strongest large Corporate proponent of "Openness" in software directly creating Java, MySQL, and having strongly contributed to the vision that produced Linux (through open UNIX work), and PHP (which owes at least some of its inception to Sun’s java server pages). The whole LAMP stack traces at least some of its roots back to Sun (Apache owning the least to Sun, but you get my meaning).

I think we are not taking account of the large position that Sun had as an intellectual proponent of openness in software. And I for one will lament its passing, especially as Oracle starts using Sun Intellectual Property as a patent-troll to quash innovation in the space.

Computer History Museum - The Facebook Effect with Mark Zuckerberg

An area of the web that has, for me, consistently a very high level of quality of discourse about computer engineering is the Computer History Museum. Its YouTube channel may be found here, http://www.youtube.com/user/ComputerHistory/videos.

I enjoyed this interview with Facebook founder Mark Zuckerberg, found here http://www.youtube.com/watch_popup?v=_TuFkupUn7k&vq=small. I found it refreshing to hear Mark (I can call him Mark, because he is one of my facebook friends), talking about the Innovation of Sharing. He tried to discuss the potentials of "sharing" over a long time frame. How this would impact the software ecosystem, and how it would create new business opportunities. Of course everyone wanted to talk to him about privacy, which was much less interesting.