WCF REST Programming Model Overview
The WCF REST Programming Model provides the basic framework elements required to build REST services with Windows Communication Foundation (WCF). REST services are designed to be accessed by the widest range of possible clients (including Web browsers with no additional client framework) and have the following unique requirements:
URIs and URI Processing. URIs play a central role in the design of REST services. The WCF REST Programming Model uses the UriTemplate and UriTemplateTable classes to provide URI processing capabilities.
Support for GET and POST operations. REST services make use of the GET verb for data retrieval, in addition to various invoke verbs for data modification and remote invocation. The WCF REST Programming Model uses the WebGetAttribute and WebInvokeAttribute to associate service operations with both GET and POST verbs.
Multiple data formats. REST services process many kinds of data. The WCF REST Programming Model uses the WebHttpBinding and WebHttpBehavior to support many different data formats including XML documents, JSON data object, and streams of binary content such as images, video files, or plain text.
The WCF REST Programming Model extends the reach of WCF to cover scenarios that include REST services, AJAX and JSON services, and Syndication (ATOM/RSS) feeds. For more information about AJAX and JSON services, see Windows Communication Support for AJAX Integration and JSON. For more information about Syndication, see WCF Syndication Overview.
.gif "Bb412172.Caution(en-us,VS.85).gif") Caution: |
|---|
| Services written with the WCF REST Programming Model do not use SOAP messages. Because SOAP is not used the security features provided by WCF cannot be used. You can, however use transport based security by hosting your service with HTTPS. For more information about WCF security, see Security Overview |
URI Processing with UriTemplate and UriTemplateTable
URI templates provide an efficient syntax for expressing large sets of structurally similar URIs. For example, the following template expresses the set of all three-segment URIs that begin with "a" and end with "c" without regard to the value of the intermediate segment: a/{segment}/c
This template describes URIs like the following:
a/x/c
a/y/c
a/z/c
and so on.
In this template, the curly brace notation ("{segment}") indicates a variable segment instead of a literal value.
.NET Framework 3.5 provides a new API for working with URI templates called UriTemplate. UriTemplates allow you to do the following:
You can call one of the Bind methods with a set of parameters to produce a fully-closed URI that matches the template. This means all variables within the URI template are replaced with actual values.
You can call Match() with a candidate URI, which uses a template to break up a candidate URI into its constituent parts and returns a dictionary that contains the different parts of the URI labeled according to the variables in the template.
Bind() and Match() are inverses so that you can call Match( Bind( x ) ) and come back with the same environment you started with.
There are many times (especially on the server, where dispatching a request to a service operation based on the URI is necessary) that you want to keep track of a set of UriTemplate objects in a data structure that can independently address each of the contained templates. UriTemplateTable represents a set of URI templates and selects the best match given a set of templates and a candidate URI. This is not affiliated with any particular networking stack (WCF included) so you can use it wherever necessary.
The WCF Service Model makes use of UriTemplate and UriTemplateTable to associate service operations with a set of URIs described by a UriTemplate. A service operation is associated with a UriTemplate, using either the WebGetAttribute or the WebInvokeAttribute. For more information about UriTemplate and UriTemplateTable, see UriTemplate and UriTemplateTable
Service Operation Parameters and URLs
REST services can be called from a Web browser by typing a URL that is associated with a service operation. These service operations may take parameters which must be specified in a string form within the URL. The following table shows the types that can be passed within a URL and the format used.
| Type | Format |
|---|---|
0 - 255 |
|
-128 - 127 |
|
-32768 - 32767 |
|
-2,147,483,648 - 2,147,483,647 |
|
-9,223,372,036,854,775,808 - 9,223,372,036,854,775,807 |
|
0 - 65535 |
|
0 - 4,294,967,295 |
|
0 - 18,446,744,073,709,551,615 |
|
-3.402823e38 - 3.402823e38 (exponent notation is not required) |
|
-1.79769313486232e308 - 1.79769313486232e308 (exponent notation is not required) |
|
Any single character |
|
Any decimal in standard notation (no exponent) |
|
True or False (case insensitive) |
|
Any string (null string is not supported and no escaping is done) |
|
MM/DD/YYYY MM/DD/YYYY HH:MM:SS [AM|PM] Month Day Year Month Day Year HH:MM:SS [AM|PM] |
|
DD.HH:MM:SS Where DD = Days, HH = Hours, MM = minutes, SS = Seconds |
|
A GUID, for example: 936DA01F-9ABD-4d9d-80C7-02AF85C822A8 |
|
MM/DD/YYYY HH:MM:SS MM:SS Where DD = Days, HH = Hours, MM = minutes, SS = Seconds |
|
Enums |
The enumeration value for example, defining the enumeration as shown in the following code.
Any of the individual enumeration values (or their corresponding integer values) may be specified in the query string. |
Types that have a TypeConverterAttribute that can convert the type to and from a string representation. |
Depends on the Type Converter. |
WebGet and WebInvoke
REST services make use of retrieval verbs (for example HTTP GET) in addition to various invoke verbs (for example HTTP POST, the verb used by SOAP services). The WCF REST Programming Model allows service developers to control the both the URI template and verb associated with their service operations with the WebGetAttribute and WebInvokeAttribute. The WebGetAttribute and the WebInvokeAttribute allow you to control how individual operations get bound to URIs and the HTTP methods associated with those URIs. For example, adding WebGetAttribute and WebInvokeAttribute in the following code.
[ServiceContract]
interface ICustomer
{
//"View It"
[OperationContract]
[WebGet]
Customer GetCustomer();
//"Do It"
[OperationContract]
[WebInvoke]
Customer UpdateCustomerName( string id,
string newName );
}
The preceding code allows you to make the following HTTP requests.
GET /GetCustomer
POST /UpdateCustomerName
WebInvokeAttribute defaults to POST but you can use it for other verbs too.
[ServiceContract]
interface ICustomer
{
//"View It“ -> HTTP GET
[OperationContract]
[WebGet( UriTemplate=“customers/{id}” )]
Customer GetCustomer( string id ):
//"Do It“ -> HTTP PUT
[OperationContract]
[WebInvoke( UriTemplate=“customers/{id}”, Method=“PUT” )]
Customer UpdateCustomer( string id, Customer newCustomer );
}
To see a complete sample of a WCF service that uses the WCF REST Programming Model, see How to: Create a Basic WCF REST Service
Formats and the WCF REST Programming Model
The WCF REST Programming Model has new features to work with many different data formats. At the binding layer, the WebHttpBinding can read and write the following different kinds of data:
XML
JSON
Opaque binary streams
This means the WCF REST Programming Model can handle any type of data but, you may be programming against Stream.
.NET Framework 3.5 provides support for JSON data (AJAX) as well as Syndication feeds (including ATOM and RSS). For more information about these features, see WCF Syndication Overview and Windows Communication Support for AJAX Integration and JSON.
WCF REST Programming Model and security
Because the WCF REST programming model does not support the WS-* protocols, the only way to secure a WCF REST service is to expose the service over HTTPS using SSL. For more information about setting up SSL with IIS 7.0, see How to implement SSL in IIS
See Also
Concepts
WCF REST Programming Object Model