Microsoft Web API – the REST is done by WCF (Part 1)

Written on April 15, 2011

Postings published on this series so far:


How to get a SOA
(c) geek&poke

When speaking of SOA today, many developers still think about Web Services (which in case of .NET are ASP.NET Web Services or Windows Communication Foundation, briefly WCF) handling SOAP using XML and other standards to enable Remote Procedure Calls (read: calling functions on remote computers).

As remote computers may be part of foreign domains or even available on the internet the need for authentication and authorization came up fast and has been satisfied by introducing the WS-Security extension to SOAP.

Another need of course has been to have reliable messaging which lead to another extension called WS-Reliability.

In order to be able to describe schemas of SOAP messages WSDL had been introduced.

As you can see, there is a great effort to exchange data between two endpoints on the network.

And even worse: the list of extensions and format definitions is by far not complete, not to mention the problems arising in the wild.

And now: the REST

Despite having all these extensions you don't feel sophisticated nor productive when using SOAP and I would state that SOA has not infiltrated IT business as buzzword-bingo scene wants to make us believe.

On the other hand, the internet grows furious day by day while reaching into all areas of our live.

Internet wouldn't be that successful if it where slow, unreliable and hard to use and manage.

Internet as most users know it using the browser of their choice is based on the HTTP protocol which carries out the functions of the web based on operations being part of the HTTP specification.

Anyone being familiar with web development should know HTTP verbs (also called "methods") like GET or POST.

But there are more verbs beneath them like the lesser known PUT or DELETE.

Furthermore HTTP uses so called Status Codes which tell the browser (e.g. with value 200 for "ok") and sometimes also the user directly (e.g. 404 for "Page not found") about the state of the current request being handled.

Based on these and some other elements of the HTTP specification in 2000 Roy Fielding wrote his dissertation where he formed a new architecture for distributed applications using web technologies: Representational State Transfer, briefly REST.

I want to point out that by no means REST based architectures must be used in web applications only. They just re-use technologies being developed for the web.

There's a URI for That

The center of a REST based architecture are resources which can be accessed by an unambiguous URI like:

Hence the book "REST in Practice" is accessibly by every client (as the case may be after authentication) when knowing this URI.

In a REST architecture a list of all books could be found here:

REST in Practice - Hypermedio and Systems Architecture

At this time we don't know which format will be returned calling both URIs nor do we know which HTTP method to use.

But in the definition of REST architectures there's a clear concept of this:

When getting data from a resource you should always use HTTP GET. This leads to the requirement that by no means the underlying data should be modified by this request so that this operation could be repeated arbitrary and always returns the same data (unless it will be modified by other methods being designated for doing that).

The format the called method will return can be chosen by the client itself (as long as the resource provides multiple formats).

However, formats are not requested by accessing as one may suppose.

It's accomplished by setting the HTTP header instead.

To request the PDF of the aforementioned book by the already known URI, the accept-type in the HTTP header is set to "application/pdf".

The URI of the book remains the same:

The header is evaluated by the server and if the PDF of the book is available, the resource delivers it in the response.

The fact that the PDF of the book is not available can also be indicated using HTTP:

By setting the status code in the HTTP header of our response to (e.g. 404 for the latter case) practically every state of a resource, request or at least the complete server hosting the resource can be represented.

Further details and sample implementations for .NET and JAVA based REST services and clients can be found in the "REST in Practice" book, which I would recommend to everyone playing around with REST.

Microsoft and REST

Of course there is a Microosft solution for REST based architectures. A few years ago Microsoft released the WCF Starter Kit. However I don't see it in the hall of fame of Microsoft products.

As REST based architectures become more and more important nowadays and of course .NET developers also need to implement or at least use it, a few month ago Microsoft has started a new project called "WCF Web API" to ease implementing REST using WCF both on server and client side - which I find has become a really good implementation until now.

The latest bits are available at

Glenn Block, the team lead of the new project has done a Session at Mix 2011 conference called "WCF Web APIs: "There's a URI for That" presenting the latest bits and samples.

Since using the WCF Web API for a while now, I'll publish a series of blog posts on the WCF Web API here in the next days.

These will not only cover the Web API itself but also testing it using the BDD framework machine.specifications/machine.fakes and wiring things up using the LightCore IoC container. Furthermore I will explain things like usage of HTTP methods like PUT and DELETE and will show off advantages of REST based architectures being implemented using WCF Web API.


Postings published on this series so far:

DotNetKicks-DE Image.aspx&bgcolor=3169AD&fgcolor=FFFFFF&border=000000&cbgcolor=D4E1ED&cfgcolor=000000)