October 30, 2014
Hot Topics:
RSS RSS feed Download our iPhone app

Creating RESTful Web Services with Windows Communication Foundation

  • August 21, 2007
  • By Aaron Lerch
  • Send Email »
  • More Articles »

Windows Communication Foundation (WCF) is Microsoft's services-oriented framework for building connected systems using the Microsoft .NET Framework. Although WCF is flexible enough to build arbitrary services-based solutions, its primary story is Web Services. To get the most out of this article, you should have at least a basic understanding of core WCF concepts including messaging, serialization, contracts, and bindings/endpoint configuration. This article was written based on .NET 3.5, the Beta 2 release.

Prior to (and including) version 3.5 of the .NET Framework, web services—whether ASMX or WCF—have been implemented using SOAP and the WS-* stack. The WS-* stack is a suite of extensions to the SOAP specification that define advanced systems-level functionality such as transactions, reliable messaging, and more. A web service was typically accessed by performing an HTTP POST to the service endpoint (for example, "http://www.example.com/ExampleService.svc") and sending a SOAP message as the submitted data. Because HTTP is a request-reply protocol, the response to the HTTP request contained a SOAP message describing the relevant response from the server. This approach to web services is by far the most prevalent in use today, and has many compelling features that make it a viable solution to many business problems. However, this approach hijacks features of the HTTP protocol, making it a "carrier" for a completely separate protocol (SOAP). For several years, a discussion has been growing over the idea that the HTTP protocol itself is rich enough to offer the capabilities that many web services require, while simultaneously providing the benefits such as scalability that the World Wide Web has enjoyed for years—benefits that a SOAP-based web service implementation does not enjoy "for free."

In .NET 3.5, WCF offers support for both worlds of programming: creating services that can be exposed via a SOAP endpoint, or a "RESTful" endpoint, depending on configuration. An alternate phrase for "REST" is "web programming." REST stands for Representational State Transfer, a term coined by one of the original authors of the HTTP protocol, Roy Fielding, in his 2000 doctoral dissertation.

Representational State Transfer

Representational State Transfer is a phrase that describes the generic principles that make up much of what we know to be the HTTP protocol. As it applies to web services, the primary concepts of interest are resources, and the actions that can be taken on a given resource. Resources are identified by Uniform Resource Identifiers (URIs), something that nearly everybody is familiar with. SOAP-based web services typically use a single URI to represent the service endpoint plus an operation. A RESTful web service uses a unique URI to reference every resource, and HTTP verbs to define actions on those resources. As an example, I will reference a simple blog engine—the source code is available for download. At the very basic level, a blog consists of posts and comments made on those posts. Retrieving a single post (a resource) using SOAP-based web services would use URI syntax much like this:

"http://blogexample.com/Blog.asmx?op=GetPost"

The URI simply serves to identify the service endpoint and the operation to invoke, not the actual resource (the specific blog post). The identifier of an individual post to retrieve would be specified inside the SOAP message contained in the body of the HTTP request. A RESTful web service would use a combination of a truly unique URI and an HTTP verb to retrieve a blog post; for example, performing an HTTP GET request to "http://blogexample.com/blog/post/123456" to retrieve blog post number 123456.

The idea of the uniqueness of the URI is of key importance. Each resource should receive its own URI. Other factors, such as the "purity" of the URI can also be important, but less so than uniqueness. The second most important facet of a RESTful web service is the use of HTTP status codes. HTTP status codes (including a "description" field) define the client-side success/error reporting mechanism. Care should be given to ensure that the appropriate status code is returned from a web request.

"URI purity", as I define it, refers to the degree with which implementation details "leak" into the URI of a resource. For example, when hosting a WCF web service in Internet Information Services (IIS, discussed later in the article) any URIs must include the service file, with a ".svc" extension. For example, retrieving blog post number 123456 might use the following URI: "http://blogexample.com/blog.svc/post/123456". The ".svc" extension is an implementation-specific detail that "muddies" the URI. If the underlying implementation changes to, say, use Ruby on Rails, the URI for the same resource would likely change. It is worth noting that "URL rewriting" can help resolve some of the implementation-specific idiosyncrasies.

What's New in WCF

"That's all fine and good", you're thinking, "but you still haven't told me anything about implementing RESTful services with WCF." Excellent point—enough background, it's time to dig in. There are several classes and attributes that have been added which extend the existing service model allowing services to be exposed as RESTful services.

System.UriTemplate

At a basic level, the UriTemplate class supports the matching or binding of a string template with name-value pairs. When defining an OperationContract, a UriTemplate is specifiedl it accomplishes two purposes. First, it provides the mapping between a request URI and an OperationContract, and second, it identifies the named values that are subsequently bound to matching OperationContract method parameters. An example of a UriTemplate instance looks like the following:

UriTemplate template =
   new UriTemplate("/post/{postid}/comments?maxresults={maxresults}");

There are some important things to know about the semantics of a UriTemplate:

  • Variable segments or parameters are specified as named values surrounded by curly braces, as in "{postid}" above. After a match, the value represented by "{postid}" will be available under the key "postid".
  • A variable must encompass an entire segment. For example, it is not valid to specify "/post/post-{id}-format/comments" as a template.
  • Query string parameter names must be literal; only the value can be parameterized.
  • A wildcard ("*") may be specified at the end of the URI template to indicate that the template matches "subsets".
  • When used in conjunction with an OperationContract, the OperationContract parameters that match the UriTemplate must be string types.

System.ServiceModel.Web.WebGetAttribute and System.ServiceModel.Web.WebInvokeAttribute

The WebGet and WebInvoke attributes are declared on an OperationContract. They use a UriTemplate, along with some additional information, to associate an HTTP request with an OperationContract and to optionally provide fine-grained control over the serialization/deserialization of the HTTP request/response data.

WebGet allows the following Properties to be specified:

Property Name Type Possible Values Description
BodyStyle WebMessageBodyStyle

Bare
Wrapped
WrappedRequest
WrappedResponse

Controls aspects of the formatting of the serialized data.
RequestFormat WebMessageFormat

Json
Xml

Specifies the deserialization format for incoming HTTP requests.
ResponseFormat WebMessageFormat

Json
Xml

Specifies the output serialization format to use for an individual OperationContract.
UriTemplate String Any string representing a parameterized relative URI The template that will be matched against incoming HTTP request URIs.




Page 1 of 3



Comment and Contribute

 


(Maximum characters: 1200). You have characters left.

 

 


Sitemap | Contact Us

Rocket Fuel