Creating a RESTful API with WCF
The talks starts with some background information about the REST support within WCF provided by Aaron Sloman. Haider Sabri continues by giving a brief introduction to REST and its principals. According to Haider the key benefits of REST are
- Low barrier of entry
- ROA follows Web Semantics ... convenient for Web Service APIs
- Flexibility in Response formats
In his opinion "REST is best choice when creating a general API when clients are unknown".
WCF supports REST through the Web Programming Model, which has been added in the .NET Framework 3.5 and consists of the following concepts:
- URI Templates & WebGet/WebInvoke
- These are attributes, which map HTTP requests to methods in a class.
- WebHttpBinding is a WCF binding that enables dispatching based on the above.
- You can easily switch between REST and a SOAP API.
- The WebOperationContext allows to manipulate requests and responses in a RESTful way.
Haider Sabri introduces RESTChess, which is a RESTful API for a chess game. RESTChess is both a nice sample of a RESTful API implemented with WCF's Web Programming Model and a bunch of extensions (custom WCF bindings and behaviors) that (partially) make up for the shortcomings of the WCF web programming model:
- Flexible URIs
- The service .svc extension is required when hosting services in IIS.
- RESTChess provides a URL rewriter implemented as a HTTP module within IIS 7.
- Bridging Low REST clients, which only support GET and POST
- There are two common approaches to solve this problem:
- Custom HTTP headers
- _method query parameter
- RESTChess implements a custom WCF channel that distinguishes between high and low REST clients and changes messages that make use of DELETE or PUT methods tunneled through a POST request to the appropriate HTTP method.
- Request Authentication with Digital Signing
- RESTChess makes use of OAuth, which is an "open protocol to allow secure API authentication" including digital signature.
- The signature is passed via an OAuth consumer key as a query parameter.
- A custom WCF channel checks the request for the OAuth key, and throws an exception before the request gets dispatched to the service model in case the consumer is not authenticated (the key is not present or unknown).
- Multiple Representation Formats
- WCF only supports XML and JSON.
- RESTful Exception Handling
- The RESTChess team build an engine to map exceptions to appropriate HTTP error codes.
Although the team had to add several missing pieces to the WCF web programming model, in Haider's opinion "the area where WCF shines is the ability to extend it, to insert into it, to build on the stack at a high level".
Interesting, but arguably an inappropriate use of REST
However, its arguable that this is not an appropriate use of the REST architectural style. REST is most appropriate when dealing with resources (indeed, Representational State Transfer is a style of software architecture that is ideal for distributed hypermedia systems, and was first identified with the World Wide Web).
I would argue XML-RPC in conjunction with HTTP authentication (or, if you like complexity for the sake of it, SOAP) to be a better fit as it implies state on the server (unlike REST), and would result in a cleaner mapping to the underlying API.
Brandon Holt, Preston Briggs, Luis Ceze, Mark Oskin May 21, 2015