Announcement: WCF Web API is now ASP.NET Web API! ASP.NET Web API released with ASP.NET MVC 4 Beta. The WCF Web API and WCF support for jQuery content on this site wll removed by the end of 2012.

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.

Click here to access our FAQ.

Quick Start

Architecture overview

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

image

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.
  • Plug in any format / media type
  • IQueryable support – Supports OData’s URI format for services
  • Designed for better separation of concerns and testability
    • Validation, URI model binding, caching, etags, etc
    • Easily integrate your IoC container
  • Simple code-based configuration model
  • Support for HTTP file upload and MIME-based batching
  • Integrated Web API test client

Team Blog posts

External resources

 

We hope you enjoy using WCF Web API. Your feedback is greatly appreciated!

Last edited Feb 17, 2012 at 7:11 PM by danroth27, version 31

Comments

tarun1982 Apr 11, 2012 at 1:28 PM 
Can i use in Windows Application(WinForm)?

spockmonster Mar 2, 2012 at 2:06 PM 
Will this API make it to Release before the Wcf RESt direction makes yet another 90 degree change in direction?

DennisvandeLaar Dec 27, 2011 at 6:08 AM 
Hi,
Does WCF Web API has build in support to deliver a page (service document) like Netflix has on this URL: http://odata.netflix.com/Catalog/

Thanks

neural9 Dec 18, 2011 at 6:29 AM 
BROKEN - the routing method. I can get all the tutorials to work using 0.5.0 but 0.6.0 throws 404 errors on any route configuration.

tlianza Sep 30, 2011 at 6:29 PM 
@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

I'm also interested in any patterns/practices for #2.

marstone Sep 22, 2011 at 3:03 PM 
Q1(Pre): any support for authorization? such as check OAuth access_token.
Q2(After): any support for field filter? such as return a var type with less fields than the pre-defined Class Object?
thanks!

tlianza Sep 16, 2011 at 7:26 PM 
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!

arielsrv Jul 7, 2011 at 5:08 PM 
How I can to generate autodocument pages in REST with WebApi?

aesopturtle Jun 28, 2011 at 6:54 AM 
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?

rpgmaker Jun 24, 2011 at 1:29 PM 
Does it support Http Streaming when hosting within a window service?

mwherman2000 May 19, 2011 at 11:01 PM 
When is it preferable to use this WCF Web API vs. the WCF Data Services Toolkit (http://wcfdstoolkit.codeplex.com/)?

Michael Herman (Toronto)

Tridus May 16, 2011 at 8:17 PM 
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.

hreisinger May 1, 2011 at 7:47 PM 
Nice work :)

Is it possible to use Custom-Headers (i.e. X-MySuperDuperCustomHeader) in the HttpResponseMessage<T> and HttpRequestMessage<T> classes (by default, or by simple extending them?)

gblock Apr 24, 2011 at 4:35 PM 
@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.

gblock Apr 24, 2011 at 4:27 PM 
@ctaswell It's not months and it's not years. Can't say definitvely.

The_Coder Feb 1, 2011 at 4:41 AM 
How this is different from WCF REST Toolkit? can you please provide detailed comparison ...

ctaswell Dec 7, 2010 at 11:00 PM 
Any tentative timeline to release candidate? To final release? Weeks, months, quarters?

Some kind of timeline even the most tentative would be helpful...