REST, WCF 4, Forms Authentication, and Custom Clients (Part 2 of 3)

Jason Williams
Dec 31, 2011 on 21:31PM
Development WCF REST
No Comments.

In the first part of this post, I discussed REST and how it compares to SOAP-based services. In this part, we’ll figure out how to create a REST service with WCF and what it takes to start thinking in a “RESTful” way when designing a REST service.

[more]

Design and Planning

A lot of services are used for basic CRUD operations. Create, Retrieve, Update, and Delete are tasks that any line-of-business service is going to need to perform. With a SOAP service, you might layout your service methods like this:

        1: [ServiceContract]

       2:     public interface ICustomerService

       3:     {

       4:         [OperationContract]

       5:         ServiceResponse<Customer> AddCustomer(Customer cust);

       6:         [OperationContract]

       7:         IEnumerable<Customer> SearchCustomers(string searchTerm, int page, int recordsPerPage);

       8:         [OperationContract]

       9:         Customer GetCustomer(int customerId);

        [OperationContract]

        ServiceResponse<Customer> UpdateCustomer(Customer cust);

        [OperationContract]

        ServiceResponse<Customer> DeleteCustomer(int customerId);

    }

 

    [DataContract]

    public class Customer

    {

        [DataMember]

        public int CustomerId { get;set;}

        [DataMember]

        public string FirstName { get; set; }

 

        [DataMember]

        public string LastName { get; set; }

    }

 

    [DataContract]

    public class ServiceResponse<T>

    {

        [DataMember]

        public T StoredEntity { get;set; }

        [DataMember]

        public bool Success { get;set; }

        [DataMember]

        public string ErrorMessage { get;set;}

    }

If you’re familiar with WCF, the attributes on these contracts should look familiar. By default, in a Visual Studio WCF Service Application (see VS 2010 Screenshot below), this contract will define a SOAP service with 5 distinct methods. For brevity’s sake, I have excluded the actual implementation of the service.

The data contracts consist of a simple Customer Entity and a wrapper class to return some information back to the user about any errors that occurred during processing.

If you would like to learn more about WCF services, I encourage you to visit Basic WCF Programming to learn more about how this all fits together.

Getting Started With REST

To allow your WCF service to behave as if it were a REST service, you will need to add the following XML to the <system.serviceModel /> element in your web.config:

       1: <services>

       2:   <service name="RESTDatabaseService.CustomerService">

       3:     <endpoint kind="webHttpEndpoint" contract="RESTDatabaseService.ICustomerService" />

       4:   </service>

       5: </services>

Once that is done, you’ll need to alter your service contract (ICustomerService, in this case) to read:

       1: [ServiceContract]

       2: public interface ICustomerService

       3: {

       4:     [OperationContract]

       5:     [WebInvoke(Method="POST")]

       6:     ServiceResponse<Customer> AddCustomer(Customer cust);

       7:  

       8:     [OperationContract]

       9:     [WebInvoke(Method="GET", UriTemplate="/{searchTerm}?page={page}&pageSize={recordsPerPage}")]

      10:     IEnumerable<Customer> SearchCustomers(string searchTerm, int page, int recordsPerPage);

      11:     

      12:     [OperationContract]

      13:     [WebInvoke(Method="GET", UriTemplate="/?id={customerId}")]

      14:     Customer GetCustomer(int customerId);

      15:     

      16:     [OperationContract]

      17:     [WebInvoke(Method="PUT")]

      18:     ServiceResponse<Customer> UpdateCustomer(Customer cust);

      19:     

      20:     [OperationContract]

      21:     [WebInvoke(Method="DELETE", UriTemplate="/?id={customerId}")]

      22:     ServiceResponse<Customer> DeleteCustomer(int customerId);

      23: }

Once those changes are made, you can now access your data via a URL. If you take a look at the WebInvoke attribute that is applied to each of the operations, you’ll notice that some of them define a UriTemplate. That template will dictate what has to come after the “CustomerService.svc” part of the URL for the operation to be invoked.

For instance, if I wanted to perform a search for everyone named “smith”, I would call the URL:

http://<server>/CustomerService.svc/smith?page=1&pageSize=10

You’ll notice the address for the service remains similar to what you would expect (starts with server name and contains /CustomerService.svc), but it ends with a string that matches the pattern in the UriTemplate argument on the SearchCustomers(…) service operation.

This works great. However, I’m not real happy with the CustomerService.svc, in the URL. It just doesn’t smell right. So, I want to change things to make my URL prettier -- like:

http://<server>/Customers/smith?page=1&pageSize=10

To do this, you’ll need to add a Global.asax to your web site: In Solution Explorer, right-click the web-site project and choose Add –> New Item… (Ctrl + Shift + A), and choose the “Global Application Class” item. Leave its default name and click “Add.”

You will also need to add a reference to the “System.ServiceModel.Activation.dll” assembly.

On your service implementation (code in CustomerService.svc.cs), add the AspNetCompatibilityRequirements attribute to the service and require compatibility, like this:

       1: [AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Required)]

       2: public class CustomerService : ICustomerService

You will also need to tell WCF to enable ASP.NET Compatibility by changing the web.config. In the <system.ServiceModel /> element, change the <serviceHostingEnvironment/ > element by adding the “aspNetCompatibilityEnabled” attribute and setting it to “true” as follows:

       1: <serviceHostingEnvironment multipleSiteBindingsEnabled="true" aspNetCompatibilityEnabled="true" />

Finally, in the new Global.asax file, add the following code:

       1: protected void Application_Start(object sender, EventArgs e)

       2: {

       3:     RegisterRoutes();

       4: }

       5:  

       6: private void RegisterRoutes()

       7: {

       8:     var factory = new System.ServiceModel.Activation.WebServiceHostFactory();

       9:     System.Web.Routing.RouteTable.Routes.Add(new System.ServiceModel.Activation.ServiceRoute("customers", factory, typeof(CustomerService)));

      10: }

After all of that, you should be able to navigate your browser to:

http://<server>/Customers/smith?page=1&pageSize=10

Striving for True RESTful-ness

REST services are not just a different protocol for delivery, they are a different way to think about your services. Roy Fielding is typically credited with coining the term “REST” in his doctoral dissertation (chapter 5); in which he lays out his vision of Representational State Transfer (REST) as a service architecture.

One of the main differences between a SOAP/RPC-style of service and a RESTful one is that the RESTful service uses its data to guide the consumer around the service; opposed to a consumer downloading a WSDL and obtaining intimate details about a service. A RESTful service will provide hints about how it should be called, next. If you’ve done any web programming, it’s similar to providing links that your user can click on, or a post-back URL in a <form /> tag.

Because of this requirement, we need to think a little more about what gets returned to our consumers. We need to modify the data contracts to include some actions that can be taken on the data that gets returned.

As an example, I want to modify the SearchCustomers(…) method to not just return data, but to also return links to the next and previous pages of data.

So far, a GET call to “http://<server>/Customers/smith?page=1&pageSize=10” will result in data similar to this:

       1: <ArrayOfCustomer xmlns="http://schemas.datacontract.org/2004/07/RESTDatabaseService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

       2:   <Customer>

       3:     <CustomerId>1</CustomerId>

       4:     <FirstName>First1</FirstName>

       5:     <LastName>Smith1</LastName>

       6:   </Customer>

       7:   <Customer>

       8:     <CustomerId>2</CustomerId>

       9:     <FirstName>First2</FirstName>

    <LastName>Smith2</LastName>

  </Customer>

  <Customer>

    <CustomerId>3</CustomerId>

    <FirstName>First3</FirstName>

    <LastName>Smith3</LastName>

  </Customer>

  <Customer>

    <CustomerId>4</CustomerId>

    <FirstName>First4</FirstName>

    <LastName>Smith4</LastName>

  </Customer>

  <Customer>

    <CustomerId>5</CustomerId>

    <FirstName>First5</FirstName>

    <LastName>Smith5</LastName>

  </Customer>

  <Customer>

    <CustomerId>6</CustomerId>

    <FirstName>First6</FirstName>

    <LastName>Smith6</LastName>

  </Customer>

  <Customer>

    <CustomerId>7</CustomerId>

    <FirstName>First7</FirstName>

    <LastName>Smith7</LastName>

  </Customer>

  <Customer>

    <CustomerId>8</CustomerId>

    <FirstName>First8</FirstName>

    <LastName>Smith8</LastName>

  </Customer>

  <Customer>

    <CustomerId>9</CustomerId>

    <FirstName>First9</FirstName>

    <LastName>Smith9</LastName>

  </Customer>

  <Customer>

    <CustomerId>10</CustomerId>

    <FirstName>First10</FirstName>

    <LastName>Smith10</LastName>

  </Customer>

</ArrayOfCustomer>

That is because an IEnumerable, when serialized by the DataContractSerializer, becomes an ArrayOf XML element, by default. Instead of returning a straight IEnumerable, we need to create a type that contains the returned elements, and includes the links we want to provide to the consumer. That type might look like this:

       1: [DataContract(Name="PagedServiceResponse")]

       2: public class PagedServiceResponse<T>

       3: {

       4:     public PagedServiceResponse()

       5:     {

       6:         Results = new List<T>();

       7:     }

       8:  

       9:     [DataMember]

      10:     public string PreviousPage { get; set; }

      11:  

      12:     [DataMember]

      13:     public string NextPage { get; set; }

      14:  

      15:     [DataMember]

      16:     public List<T> Results { get; set; }

      17: }

If we return that type; filled with Customer objects, we’ll see output like this:

       1: <PagedServiceResponse xmlns="http://schemas.datacontract.org/2004/07/RESTDatabaseService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

       2:   <NextPage>http://localhost:63608/customers/Smith?page=4&amp;pageSize=10</NextPage>

       3:   <PreviousPage>http://localhost:63608/customers/Smith?page=2&amp;pageSize=10</PreviousPage>

       4:   <Results>

       5:     <Customer>

       6:       <CustomerId>21</CustomerId>

       7:       <FirstName>First21</FirstName>

       8:       <LastName>Smith21</LastName>

       9:     </Customer>

    <Customer>

      <CustomerId>22</CustomerId>

      <FirstName>First22</FirstName>

      <LastName>Smith22</LastName>

    </Customer>

    <Customer>

      <CustomerId>23</CustomerId>

      <FirstName>First23</FirstName>

      <LastName>Smith23</LastName>

    </Customer>

    <Customer>

      <CustomerId>24</CustomerId>

      <FirstName>First24</FirstName>

      <LastName>Smith24</LastName>

    </Customer>

    <Customer>

      <CustomerId>25</CustomerId>

      <FirstName>First25</FirstName>

      <LastName>Smith25</LastName>

    </Customer>

    <Customer>

      <CustomerId>26</CustomerId>

      <FirstName>First26</FirstName>

      <LastName>Smith26</LastName>

    </Customer>

    <Customer>

      <CustomerId>27</CustomerId>

      <FirstName>First27</FirstName>

      <LastName>Smith27</LastName>

    </Customer>

    <Customer>

      <CustomerId>28</CustomerId>

      <FirstName>First28</FirstName>

      <LastName>Smith28</LastName>

    </Customer>

    <Customer>

      <CustomerId>29</CustomerId>

      <FirstName>First29</FirstName>

      <LastName>Smith29</LastName>

    </Customer>

    <Customer>

      <CustomerId>30</CustomerId>

      <FirstName>First30</FirstName>

      <LastName>Smith30</LastName>

    </Customer>

  </Results>

</PagedServiceResponse>

We’re almost there! The last thing we should probably do is provide a direct link to the individual customer record details. To do this, we’ll create a new domain object like this:

       1: [DataContract(Name="Customer")]

       2: public class LinkedCustomer : Customer

       3: {

       4:     public LinkedCustomer(Customer c)

       5:     {

       6:         this.FirstName = c.FirstName;

       7:         this.LastName = c.LastName;

       8:         this.CustomerId = c.CustomerId;

       9:     }

      10:     [DataMember]

      11:     public string Link { get; set; }

      12: }

Finally, we get the following result:

       1: <PagedServiceResponse xmlns="http://schemas.datacontract.org/2004/07/RESTDatabaseService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

       2:   <NextPage>http://localhost:63608/customers/Smith?page=4&amp;pageSize=10</NextPage>

       3:   <PreviousPage>http://localhost:63608/customers/Smith?page=2&amp;pageSize=10</PreviousPage>

       4:   <Results>

       5:     <Customer>

       6:       <CustomerId>21</CustomerId>

       7:       <FirstName>First21</FirstName>

       8:       <LastName>Smith21</LastName>

       9:       <Link>http://localhost:63608/customers/?id=21</Link>

    </Customer>

    <Customer>

      <CustomerId>22</CustomerId>

      <FirstName>First22</FirstName>

      <LastName>Smith22</LastName>

      <Link>http://localhost:63608/customers/?id=22</Link>

    </Customer>

    <Customer>

      <CustomerId>23</CustomerId>

      <FirstName>First23</FirstName>

      <LastName>Smith23</LastName>

      <Link>http://localhost:63608/customers/?id=23</Link>

    </Customer>

    <Customer>

      <CustomerId>24</CustomerId>

      <FirstName>First24</FirstName>

      <LastName>Smith24</LastName>

      <Link>http://localhost:63608/customers/?id=24</Link>

    </Customer>

    <Customer>

      <CustomerId>25</CustomerId>

      <FirstName>First25</FirstName>

      <LastName>Smith25</LastName>

      <Link>http://localhost:63608/customers/?id=25</Link>

    </Customer>

    <Customer>

      <CustomerId>26</CustomerId>

      <FirstName>First26</FirstName>

      <LastName>Smith26</LastName>

      <Link>http://localhost:63608/customers/?id=26</Link>

    </Customer>

    <Customer>

      <CustomerId>27</CustomerId>

      <FirstName>First27</FirstName>

      <LastName>Smith27</LastName>

      <Link>http://localhost:63608/customers/?id=27</Link>

    </Customer>

    <Customer>

      <CustomerId>28</CustomerId>

      <FirstName>First28</FirstName>

      <LastName>Smith28</LastName>

      <Link>http://localhost:63608/customers/?id=28</Link>

    </Customer>

    <Customer>

      <CustomerId>29</CustomerId>

      <FirstName>First29</FirstName>

      <LastName>Smith29</LastName>

      <Link>http://localhost:63608/customers/?id=29</Link>

    </Customer>

    <Customer>

      <CustomerId>30</CustomerId>

      <FirstName>First30</FirstName>

      <LastName>Smith30</LastName>

      <Link>http://localhost:63608/customers/?id=30</Link>

    </Customer>

  </Results>

</PagedServiceResponse>

Of course, this type can be modified to be re-used by the GetCustomer(…) method so that it also includes the URLs for saving the item back to the service and deleting it. Providing feedback to your service consumer, in this manner, allows you to change your service layout, later; while not affecting the consumer’s ability to use the service. This is because the consumer never has to hard-code any URL information; instead they pull it from the message returned by the service.

Pick Your Formatting

So far, we have a service that will respond very well to basic HTTP calls and return very useful information – in XML. However, what if a JavaScript consumer calls the service and wants JSON messages back, instead? Fortunately, because of the way WCF is designed, you can control this with only a few lines of configuration.

In the web.config, add the following XML to the <system.serviceModel /> element:

       1: <standardEndpoints>

       2:   <webHttpEndpoint>

       3:     <standardEndpoint automaticFormatSelectionEnabled="true" helpEnabled="true" />

       4:   </webHttpEndpoint>

       5: </standardEndpoints>

The “automaticFormatSelectionEnabled” is the real magic, here. This instructs WCF to inspect the HTTP headers for Accept and Content-Type; to determine what kind of formatting the consumer is asking for. After that, WCF picks the correct serializer, for you, and you don’t have to worry about it. Cool, eh?!

Another nicety I should mention is the “helpEnabled" attribute. This enables consumers to navigate to http://<server>/Customers/help and see documentation for your service. Here’s a screenshot of what comes back in a browser:

In essence, as a consumer, you end up with an interactive document that helps you format your messages and URLs and gives you examples of what returns back from the service. This is incredibly useful and once again, it’s all done for you!

Summary

So, what have we done so far? In Part 1 of this post we saw some simple differences between SOAP and REST architectures. In this post, we saw how simple it is to convert a basic WCF service into a REST service; using a couple lines of configuration, and the addition of the WebInvoke attribute to the service contract.

We also saw how we can use ASP.NET routing to make the service URL more “pretty” and get rid of the .svc extension on the service, itself. Additionally, to stay true to the way REST services are suppose to work, we saw one example of how we might add links to other service actions in our return messages. Just because your service is accessed via a URL and an HTTP verb doesn’t make it truly RESTful. You have to think about your consumers in a different way than if they had downloaded all of the details of your service from a WSDL.

Lastly, we looked at the formatting of the data that comes out of the service. It’s very simple to enable flexible formatting; with only a few lines of configuration. Additionally, it’s just as easy to provide online help and documentation to your service consumers using the “helpEnabled” configuration attribute.

In the upcoming Part 3 of this post, we’ll add a client / consumer to the service and, just to make things more interesting, tack on some security to make this hypothetical service a little more real-world-ready.