Microsoft Release New REST API Framework as Part of .NET 4.5

As part of the recent Visual Studio 2012 and .NET 4.5 launch, Microsoft formally unveiled its new web services framework called the ASP.NET Web API. Included as part of the ASP.NET MVC 4 offering, the open-source ASP.NET Web API is designed to simplify the development and consumption of RESTful services.

In a post called “Where does ASP.NET Web API Fit?”, Rick Strahl of West Wind Technologies explains the purpose and benefits of the ASP.NET Web API.

ASP.NET Web API differentiates itself from the previous Microsoft in-box HTTP service solutions in that it was built from the ground up around the HTTP protocol and its messaging semantics. Unlike WCF REST or ASP.NET AJAX with ASMX, it’s a brand new platform rather than bolted on technology that is supposed to work in the context of an existing framework. The strength of the new ASP.NET Web API is that it combines the best features of the platforms that came before it, to provide a comprehensive and very usable HTTP platform. Because it's based on ASP.NET and borrows a lot of concepts from ASP.NET MVC, Web API should be immediately familiar and comfortable to most ASP.NET developers.

Strahl points out the core capabilities that make the ASP.NET Web API a natural fit for both existing users of the the ASP.NET MVC framework, and developers who need to build HTTP endpoints.

Strong Support for URL Routing to produce clean URLs using familiar MVC style routing semantics
Content Negotiation based on Accept headers for request and response serialization
Support for a host of supported output formats including JSON, XML, ATOM
Strong default support for REST semantics but they are optional
Easily extensible Formatter support to add new input/output types
Deep support for more advanced HTTP features via HttpResponseMessage and HttpRequestMessage
classes and strongly typed Enums to describe many HTTP operations
Convention based design that drives you into doing the right thing for HTTP Services
Very extensible, based on MVC like extensibility model of Formatters and Filters
Self-hostable in non-Web applications
Testable using testing concepts similar to MVC
Microsoft already has an existing a web services framework called Windows Communication Foundation (WCF) which lets developers build contract-first services that leverage transport protocols such as TCP, HTTP and MSMQ. Originally built for SOAP-based services that want WS-* capabilities, WCF eventually added a handful of REST-friendly capabilities. While the ASP.NET Web APIs were initially aligned to the WCF framework, they were eventually shuffled over to the ASP.NET team as described in a Code Project article by Web developer Ido Flatow.

As time passed, the WCF Web APIs had a lot of trouble adapting WCF to the “native” HTTP world. As WCF was primarily designed for SOAP-based XML messages, and the “open-heart” surgery that was required to make the Web API work as part of WCF was a bit too much (or so I understand from people who were involved in creating the Web APIs). On the other hand, the ASP.NET MVC infrastructure with its elegant handling of HTTP requests and responses, and its support of easy-to-create controllers seemed like the proper way to go for creating this new type of services.

WCF remains alive and well in the latest .NET 4.5 release and Flatow identifies some of the decision criteria for choosing between WCF and the ASP.NET Web API.

If your intention is to create services that support special scenarios – one way messaging, message queues, duplex communication etc, then you’re better of picking WCF
If you want to create services that can use fast transport channels when available, such as TCP, Named Pipes, or maybe even UDP (in WCF 4.5), and you also want to support HTTP when all other transports are unavailable, then you’re better off with WCF and using both SOAP-based bindings and the WebHttp binding.
If you want to create resource-oriented services over HTTP that can use the full features of HTTP – define cache control for browsers, versioning and concurrency using ETags, pass various content types such as images, documents, HTML pages etc., use URI templates to include Task URIs in your responses, then the new Web APIs are the best choice for you.
If you want to create a multi-target service that can be used as both resource-oriented service over HTTP and as RPC-style SOAP service over TCP – talk to me first, so I’ll give you some pointers.
The ASP.NET Web API is included in Visual Studio 2012 and is also available as a download for Visual Studio 2010 users. Developers looking to get started with the framework will find many example projects available on the team’s Codeplex site.

Use IAPIExplorer To List Your ASP.NET Web APIs

IApiExplorer is a new abstraction layer that allows you to obtain a description of the structure of your ASP.NET Web APIs. This interface also comes with a default implementation - APIExplorer.

IApiExplorer is an abstraction layer that allows you to obtain a description of the structure of your Web APIs. This information can be used to produce documentation, machine-readable metadata, or a test client.

ApiExplorer is the default implementation of IApiExplorer that inspects the routes and other Web API constructs to produce the description.

Some of the things you can do with this API -
Produce Documentation
Create Machine Readable Metadata
Create a Test Client

The main goal of this class is to produce a collection of ApiDescription. It does so by statically inspecting the routes and the available actions inside your controllers. Each ApiDescription describes an API that is available on your service. As you can see from the simplified class diagram below, the ApiDescription contains basic information such as the HttpMethod, the RelativePath, the Documentation, etc. But it also points to an ActionDescriptor which is part of the core Web API component that knows everything about an action. You can use it to access a lot more information such as the action name, the return type, the custom attributes, etc. Similarly, you can access the ParameterDescriptor for the expected parameters.

Microsoft Users DevCon returns to Trivandrum next weekend

The Kerala Microsoft Users Group (K-MUG) will be organising their next Developers Conference, DevCon 2012 on May 19, 2012 at the Park Centre in Technopark, Trivandrum. Billed as the largest Microsoft tech event in Kerala, DevCon 2012 would see a large number of software professionals engage and collaborate with Microsoft MVPs and other IT peers. The key attractions this time would be the Windows Phone and Windows 8 sessions.

Interacting with Kerala IT News, Sreejumon K P, one of the organisers, said, “There are three tracks on Windows Phone and I am sure this will attract many .NET developers into the Windows Phone ecosystem and application development. For the first time we are also doing a preview of Windows 8, the upcoming edition of the Windows Operating System from Microsoft, for the techies in Kerala.

Access Any Data Any Where, XNA based game development for Windows Phone, Visual Studio 11, Windows Phone App Development - HTML5, Hybrid & Cross Platform, ASP.NET Web APIs and Tips and Best Practices for Windows Phone Development are some of the sessions planned for the Developer Conference.

“We have an idea contest as well happening. The shortlisted attendees will present their ideas and a panel will select the top three ideas. The topper would get a Nokia Lumia 800 and all the great ideas will get support from Nokia to develop their application and submit in to Market place”, added Sreejumon.

The last Developers Conference to be held in Thiruvananthapuram was DevCon 2010 in July, 2010. Check out the DevCon 2012 homepage to get details about the sessions, speakers and for registration.

WCF 4.5 and the ASP.NET Web API got some cool changes.

WCF Simplification Features:

Simplified Generated Configuration Files
When you add a service reference in Visual Studio or use the SvcUtil.exe tool, a client configuration file is generated. In previous versions of WCF these configuration files contained the value of every binding property even if its value is the default value. In WCF 4.5 the generated configuration files contain only those binding properties that are set to a non-default value.

Contract-First Development
WCF now has support for contract-first development. The svcutl.exe has a /serviceContract switch which allows you to generate service and data contracts from a WSDL document.

Add Service Reference from a Portable Subset Project
Portable subset projects enable .NET assembly programmers to maintain a single source tree and build system while still supporting multiple .NET platforms (desktop, Silverlight, Windows Phone, and XBOX). Portable subset projects only reference .NET portable libraries which are a .NET framework assembly that can be used on any core .NET platform. The developer experience is the same as adding a service reference within any other WCF client application. For more information, see Add Service Reference in a Portable Subset Project.

ASP.NET Compatibility Mode Default Changed
WCF provides ASP.NET compatibility mode to grant developers full access to the features in the ASP.NET HTTP pipeline when writing WCF services. To use this mode, you must set the aspNetCompatibilityEnabled attribute to true in the <serviceHostingEnvironment> section of web.config. Additionally, any service in this appDomain needs to have the RequirementsMode property on its AspNetCompatibilityRequirementsAttribute set to Allowed or Required. By default AspNetCompatibilityRequirementsAttributeis now set to Allowed. For more information, see What's New in Windows Communication Foundation 4.5 and WCF Services and ASP.NET.

XmlDictionaryReaderQuotas
XmlDictionaryReaderQuotas contains configurable quota values for XML dictionary readers which limit the amount of memory utilized by an encoder while creating a message. While these quotas are configurable, the default values have changed to lessen the possibility that a developer will have to set them explicitly.

WCF Configuration Validation
As part of the build process within Visual Studio, WCF configuration files are now validated for attributes defined within the project. A list of validation errors or warnings is displayed in Visual Studio if the validation fails.


XML Editor Tooltips
In order to help new and existing WCF service developers to configure their services, the Visual Studio XML editor now provides tooltips for every configuration element and its properties that is part of the service configuration file.

Streaming Improvements
Added support for true asynchronous streaming where the send side now does not block threads if the receive side is not reading or slow in reading thereby increasing scalability. Removed the limitation of message buffering when a client sends a streamed message to an IIS hosted WCF service.

Simplifying Exposing an Endpoint Over HTTPS with IIS
An HTTPS protocol mapping has been added to simplify exposing an endpoint over HTTPS. To enable an HTTPS endpoint, ensure your website has an HTTPS binding and SSL certificate configured, and then simply enable HTTPS for the virtual directory that hosts the service.


Generating a Single WSDL Document
Some third-party WSDL processing stacks are not able to process WSDL documents that have dependencies on other documents through a xsd:import. WCF now allows you to specify that all WSDL information be returned in a single document. To request a single WSDL document append “?singleWSDL” to the URI when requesting metadata from the service.

WebSocket Support
WebSockets is a technology that provides true bidirectional communication over ports 80 and 443 with performance characteristics similar to TCP. Two new bindings have been added to support communication over a WebSocket transport. NetHttpBinding and NetHttpsBinding. For more information see: System-Provided Bindings.

XML Editor Tooltips
In order to help new and existing WCF service developers to configure their services, the Visual Studio XML editor now provides tooltips for every configuration element and its properties that is part of the service configuration file.

Configuring WCF Services in Code
Windows Communication Foundation (WCF) allows developers to configure services using configuration files or code. Configuration files are useful when a service needs to be configured after being deployed. When using configuration files, an IT professional only needs to update the configuration file, no recompilation is required. Configuration files, however, can be complex and difficult to maintain. There is no support for debugging configuration files and configuration elements are referenced by names which makes authoring configuration files error-prone and difficult. WCF also allows you to configure services in code. In earlier versions of WCF (4.0 and earlier) configuring services in code was easy in self-hosted scenarios, the ServiceHost class allowed you to configure endpoints and behaviors prior to calling ServiceHost.Open. In web hosted scenarios, however, you don’t have access to the ServiceHost class. To configure a web hosted service you were required to create a ServiceHostFactory that created the ServiceHost and performed any needed configuration. Starting with .NET 4.5, WCF provides an easier way to configure both self-hosted and web hosted services in code. For more information, see Configuring WCF Services in Code.

ChannelFactory Caching
WCF client applications use the ChannelFactory class to create a communication channel with a WCF service. Creating ChannelFactory instances incurs some overhead because it involves the following operations:

1. Constructing the ContractDescription tree

2. Reflecting all of the required CLR types

3. Constructing the channel stack

4. Disposing of resources

Compression and the Binary Encoder
Beginning with WCF 4.5 the WCF binary encoder adds support for compression. The type of compression is configured with the CompressionFormat property. Both the client and the service must configure the CompressionFormat property. Compression will work for HTTP, HTTPS, and TCP protocols. If a client specifies to use compression but the service does not support it a protocol exception is thrown indicating a protocol mismatch. For more information, see Choosing a Message Encoder

UDP
Support has been added for a UDP transport which allows developers to write services that use “fire and forget” messaging. A client sends a message to a service and expects no response from the service.

Multiple Authentication Support
Support has been added to support multiple authentication modes, as supported by IIS, on a single WCF endpoint when using the HTTP transport and transport security. IIS allows you to enable multiple authentication modes on a virtual directory, this feature allows a single WCF endpoint to support the multiple authentication modes enabled for the virtual directory where the WCF service is hosted.

IDN Support
Support has been added to allow for WCF services with Internationalized Domain Names. For more information see WCF and Internationalized Domain Names.

HttpClient
A new class called HttpClient has been added to make working with HTTP requests much easier. For more info, see Making apps social and connected with HTTP services and HttpClient Upload Sample.

Configuration Intellisense
Attribute values in configuration files for custom attributes defined in the project now support intellisense to facilitate working with configurations quickly and accurately.

Configuration tooltips
WCF elements and attributes now have tooltips in the XML editor, to more easily and accurately identify the purpose of the element or attribute.

Paste Data as Classes
In a WCF project, data types defined in XML (such as are exposed in a service) can be pasted directly into a code page. The XML type will be pasted as a CLR type. See Using Paste XML as Classes for more details.

ASP.NET MVC, Web API, Razor and Open Source

Microsoft has made the source code of ASP.NET MVC available under an open source license since the first V1 release. We’ve also integrated a number of great open source technologies into the product, and now ship jQuery, jQuery UI, jQuery Mobile, jQuery Validation, Modernizr.js, NuGet, Knockout.js and JSON.NET as part of it.

I’m very excited to announce today that we will also release the source code for ASP.NET Web API and ASP.NET Web Pages (aka Razor) under an open source license (Apache 2.0), and that we will increase the development transparency of all three projects by hosting their code repositories on CodePlex. Doing so will enable a more open development model where everyone in the community will be able to engage and provide feedback on code checkins, bug-fixes, new feature development, and build and test the products on a daily basis using the most up-to-date version of the source code and tests.

We will also for the first time allow developers outside of Microsoft to submit patches and code contributions that the Microsoft development team will review for potential inclusion in the products. We announced a similar open development approach with the Windows Azure SDK last December, and have found it to be a great way to build an even tighter feedback loop with developers – and ultimately deliver even better products as a result.

Very importantly - ASP.NET MVC, Web API and Razor will continue to be fully supported Microsoft products that ship both standalone as well as part of Visual Studio (the same as they do today). They will also continue to be staffed by the same Microsoft developers that build them today (in fact, we have more Microsoft developers working on the ASP.NET team now than ever before). Our goal with today’s announcement is to increase the feedback loop on the products even more, and allow us to deliver even better products. We are really excited about the improvements this will bring.