WCF Web API Overview

What is WCF Web API?

Applications are continually evolving to expose their functionality over the web for example social services like
Flickr, Twitter and
Facebook. Aside from social applications, organizations are also looking to surface their core enterprise business functionality to an ever expanding array of client platforms. WCF Web API allows developers to expose their
applications, data and services to the web directly over
HTTP. This allows developers to fully harness the richness of the HTTP as an application layer protocol. Applications can communicate with a very broad set of clients whether they be browsers, mobile devices, desktop applications or other backend services.
They can also take advantage of the caching and proxy infrastructure of the web through providing proper control and entity headers. We are designing specifically to support applications built with a
RESTful architecture style though it does not force developers to use REST. The benefits of REST for your applications include discoverability, evolvability and scalability.

Quick Start

Architecture overview

Below is a high level diagram of the WCF Web API architecture

HTTP Client– WCF Web API introduces a new HTTP client (HttpClient) for sending HTTP requests and receiving HTTP responses. The new client has been built very tightly in accordance with the
HTTP specification and allows developers to consume any HTTP service. WCF Web API also adds a set of extension methods for simplifying the conversion of the HTTP body to and from .NET classes. The
HTTP client provides HttpRequestMessage and HttpResponseMessage abstractions, which are strongly typed representations of an HTTP message. WCF Web API uses these new types the server as well for a fully symmetric experience.

Listener – This component listens over HTTP and accepts an incoming HTTP message. The listener has a specific base address like “http://www.contoso.com” that it monitors incoming traffic on.

HTTP Channel stack – WCF Web API is agnostic to the hosting environment as it can be hosted on ASP.NET, directly on IIS or self-hosted in a desktop front end, or a backend process like a windows service. At the hosting later we transform
the raw incoming HTTP message into our new HttpRequestMessage and we transform outgoing HttpResponseMessage instances into a raw HTTP response. At the channel layer low level concerns can be addressed such as plugging in an OAuth channel for handling security,
or logging of all messages. The new HttpMessageHandler API provides a simple to use extension point for developers to easily plug in such concerns.

Dispatcher – The dispatcher is responsible for routing the current http request to an http service instance and a method on that service. The service and method are matched based on the URI and HTTP method (GET, POST, PUT, DELETE,
etc). At this layer serialization is also handled, allowing the body of the HTTP message or other components to be transformed to and from .NET types. In WCF Web API we’ve introduced a new extensibility point called MediaTypeFormatter which allows developers
to easily plug in their own media type format support(including those that support hypermedia) which can act on both the body as well as other components of the message like the URI. Media type formatters can also be used for addressing other cross-cutting
HTTP concerns like ETags. Processors are also designing to easily testable.

HTTP Service – The service is the place where developers add custom handling code and business logic for an HTTP request. With WCF Web API developers can get direct access to the underlying HTTP request and response through parameters
on the operations rather than through static APIs (like WebOperationContext). The new request and response message types make WCF Web API much easier to unit test.

*For those familiar with WCF this may look similar to diagrams you have seen of our previous releases. The primary difference here is that the components within the various layers are now specific to HTTP.

Features

First-class programming model for HTTP in WCF

Access HTTP from top to bottom

Content negotiation

HttpClient

Out of the box support for XML, JSON and OData

Typeless JSON support – Allows using a dynamic object on the server for accessing the body. Useful for jQuery clients.

@marstone check out this link for the auth part (#1). I haven't tried it yet, but looks pretty good: http://blogs.msdn.com/b/rjacobs/archive/2010/06/14/how-to-do-api-key-verification-for-rest-services-in-net-4.aspx

This is great stuff guys - IMO it's the most important thing going in the WCF stack. From an end-to-end perspective though, are there any good examples of taking a LINQ datamodel and exposing it in this fashion?

LINQ has support for serialization, but it's "all or nothing" and you can't hide certain values from the outside world. Or, more precisely, you might actually want your serialization to disk to include everything, but the serialized version of the objects you expose via HTTP to hide certain things, or be a bit more consumer-friendly.

So, to workaround the "two serializations" problem I've written a T4 template to convert my LINQ objects to POCO for the API. However, because neither the DataContractSerializer or XmlSerializer supports/respects MetadataTypeAttribute, again there's no way to easily decorate my datamodel with which fields should be exposed in the api.

Any thoughts/patterns would be appreciated. I'm also in Seattle if you want to chat!

How do you provide credentials to Microsoft.Net.Http.HttpClient?It used to be HttpClient.TransportSettings.Credentials but now I couldn't find such property anywhere.Has it been removed in this preview?

On the server side will there be better support for permissions and authorization rules? WCF's REST based stuff has always handled that in very ugly ways, particularly if the rules weren't incredibly simplistic.

@The Coder, the REST starter kit is official deprecated with this work. At the highest level I would think of RSK as a prototype exploring things to come. Web api is the platform pieces were are building which replace it ;-) Many of the ideas of RSK are incorporate, but we've gone much further. With web api we provide a much better end to end story for working with HTTP both on the client and the server. As in RSK we have an HTTP client, in this case which is a productized / much more stable / tested version of what is in RSK. Further than thta we offer rich support on the server to content negotiation allowing you to support any media type. RSK only included topical changes to the server, web api plumbs deeply into WCF more proper HTTP support.