1. Creating and Consuming RESTful Web Services with WCF
Ron Jacobs
Sr. Technical Evangelist
Platform Evangelism
Microsoft Corporation

2. Agenda What is REST? Is REST SOA? Key REST principles
Adventure Works REST API WCF Example
Summary
71 Slides
5 Demos
I must be insane!

3. Resources
Leonard Richardson
Sam Ruby
Code
Slides

4. “Representational state transfer (REST) is a style of software architecture for distributed hypermedia systems such as the World Wide Web.”
What is rest?

5. HTTP What is REST? Application state and functionality are resources
Every resource has a URI
All resources share a uniform interface
HTTP

6. Is REST SOA? “Protocol independence is a bug, not a feature”.
- Mark Baker
Is REST SOA?

7. IS REST SOA? SOAP REST WCF Test Client Notepad Internet Explorer
REST is an architectural style that allows you to implement services with broad reach
SOA is about services
SOA is not about protocol, transport, format etc.
SOAP
REST
WCF Test Client
Notepad
Internet Explorer
5 HTTP Messages
18,604 bytes
“You entered: 1”

8. “The promise is that if you adhere to REST principles while designing your application, you will end up with a system that exploits the Web’s architecture to your benefit.”
-Stefan Tilkov
Key rest principles

9. Key REST Principles Give every “thing” an ID Link things together
Use standard methods
Resources with multiple representations
Communicate statelessly

10. Give every “thing” an ID
Expose thing or collection things with a scheme that is ubiquitous
Embrace the URI
How to get it ( or net.tcp:// or net.msmq:// etc.)
Where to get it (example.com)
What to get (customer 1234)

11. Give every “thing” an ID
An API like this
Customer C = GetCustomer(1234);
Can be represented like this

12. Link Things Together Hypermedia as the engine of application state
Just means that you should link things together
People or apps can transition state by following links
Links can be to the same app or to some other app

13. Link Things Together
<CustomerData>
<Self>
<CompanyName>A Bike Store</CompanyName>
<CustomerID>1</CustomerID>
<FirstName>Orlando</FirstName>
<LastName>Gee</LastName>
<Orders>
<RowID>3f5ae95e-b87d-4aed-95b4-c3797afcb74f</RowID>
</CustomerData>

14. Use Standard Methods public class Resource { Resource(Uri u);
Response Get();
Response Post(Request r);
Response Put(Request r);
Response Delete();
Response Head(); }

15. Shift to Resource Thinking
Architect Connections
Shift to Resource Thinking
Operation
SQL Command
HTTP Verb
Create a resource
INSERT
POST(a), PUT
Read a resource
SELECT
GET
Update a resource
UPDATE
PUT, POST(p)
Delete a resource
DELETE
Query Metadata
(Systables)
HEAD
SQL
INSERT INTO CUSTOMERS (...) VALUES (...)
REST
(POST)
<Customer>...</Customer>
Updates will be available at

16. Shift to Resource Thinking
Operation
SQL Command
HTTP Verb
Create a resource
INSERT
POST
Read a resource
SELECT
GET
Update a resource
UPDATE
PUT (POST)
Delete a resource
DELETE
Query Metadata
(Systables)
HEAD
SQL
SELECT FROM CUSTOMERS WHERE ID=567
REST
(GET)

17. Resources as operations
The result of an operation can be considered a resource
API
var result = CalculateShipping(“Redmond”, “NYC”);
REST

18. Content Negotiation Allow the client to ask for what they want
“I want XML”
“I want JSON”
“I want …” (HTML, CSV, etc.)
GET /customers/1234 HTTP/1.1
Host: example.com
Accept: text/xml
JSR 311 features the idea
of extensions as a way
to do content negotiation
without the headers as in
/customers.xml
/customers.json
GET /customers/1234 HTTP/1.1
Host: example.com
Accept: text/json

19. Communicate Statelessly
Stateless means that every request stands alone
Session is not required
Can be bookmarked
Application State lives on the Client
Everything that is needed to complete the request must be included in the request
Resource State lives on the server(s)
Stored in durable storage (typically)
May be cached

20. adventure works REST API
Implementation Time
adventure works REST API

21. AdventureWorks Customer API
URI
Method
Collection
Operation
/customers
POST
Customers
Create
/customers/{custId}
GET
Read
PUT
Update
DELETE
Delete
/customers/{custId}/Orders
Sales
Read customer orders

22. “Remember that GET is supposed to be a “safe” operation, i. e
“Remember that GET is supposed to be a “safe” operation, i.e. the client does not accept any obligations (such as paying you for your services) or assume any responsibility, when all it does is follow a link by issuing a GET.”
-Stefan Tilkov
HTTP GET

23. GET CUSTOMER DeMO http://rojacobsxps/AdventureWorksDev/api/customer/1
WebGet Attribute
UriTemplate
Query String Parameters
GET CUSTOMER DeMO

24. WebGet Attribute
WebGet Indicates you want to use an HTTP GET for this method
Method name is resource name
Arguments are query string parameters
// GET a customer
[OperationContract]
[WebGet]
CustomerData GetCustomer(string customerId);

25. WebGet UriTemplate
UriTemplate maps the URI to parameters in your method
Using parameters in the Uri makes them mandatory, query string parameters are optional.
// GET a customer
[OperationContract]
[WebGet(UriTemplate = "customer/{customerId}")]
CustomerData GetCustomer(string customerId);

26. Making your first RESTful Service
Create a WCF Service Library
Add a reference / using
System.ServiceModel.Web
Decorate your method with WebGet
Modify configuration
Change the binding from wsHttpBinding to webHttpBinding
Add the webHttp endpoint behavior to the endpoint
Note: WCF will start up without this behavior though it is not very useful configuration

27. Gotcha!
Testing the service with the WCF Test Client

28. Gotcha! Testing with the browser before setting the webHttp behavior
What I wish they had said...
Or better yet, don’t start up without webHttp if you have WebGet on an OperationContract.
' cannot be processed at the receiver, due to an AddressFilter mismatch at the EndpointDispatcher. Check that the sender and receiver's EndpointAddresses agree.
' cannot be processed at the receiver, due to an AddressFilter mismatch at the EndpointDispatcher. Did you forget the webHttp behavior on the endpoint?

29. Testing your first RESTful service
Use a browser to test it
The default behavior is
Method name is the resource
Arguments are query strings
Add a UriTemplate to modify the default behavior

30. Architect Connections
Get Customers
Returns a collection of customers from the database
Issues
Security – you can only see orders you are allowed to see
Paging – stateless requests decide where to start
REST API
SOAP API
Customer[] GetCustomers()
Updates will be available at

31. Paging Allows clients to request a subset of the collection
Use Query String parameters to specify start index and count

32. 405 Method not allowed Gotcha! // GET customers
[OperationContract] [WebGet(UriTemplate="customer?start={start}&count={count}")]
CustomerGroupingData GetCustomers(int start, int count);
// POST to customers
[OperationContract]
[WebInvoke(UriTemplate = "customer")]
CustomerData AppendCustomer(CustomerData customer);
405 Method not allowed

33. Architect Connections
Why?
The template matching engine tries to find the best match
The more specific a match is, the better
When the URL contains just the resource “customer”
The match for “customer” is a POST method
Return 405 Method not allowed
Updates will be available at

34. Why?
Solution
Don’t include the query string parameters in the UriTemplate
Get them instead from the WebOperationContext.Current
UriTemplate is now just “customer” for both GET and POST

35. 200 Ok Solution // GET customers
[OperationContract] [WebGet(UriTemplate = "customer")]
CustomerGroupingData GetCustomers(int start, int count);
// POST to customers
[OperationContract]
[WebInvoke(UriTemplate = "customer")]
CustomerData AppendCustomer(CustomerData customer);
200 Ok

36. Query String Parameters
private string GetQueryString(string argName) { UriTemplateMatch match = WebOperationContext.Current.IncomingRequest.UriTemplateMatch; try return match.QueryParameters[argName]; } catch (KeyNotFoundException) return null;
Query String Parameters are found in here

37. Caching
Use HttpRuntime.Cache to cache items on the server if it makes sense to do so
// Check the cache
CustomerData customerData = (CustomerData)HttpRuntime.Cache[requestUri.ToString()];
// Not found in the cache
if (customerData == null) {
// Try to get the customer data
customerData = CustomersCollection.GetCustomer(custId);
// Still not found
outResponse.SetStatusAsNotFound(string.Format("Customer Id {0} not found", customerId)); }
else // found
// Set the headers
outResponse.LastModified = customerData.LastModified;
outResponse.ETag = customerData.ETag.ToString();
CacheCustomer(requestUri, customerData);

38. Client Caching
Add Expires or Cache-Control headers to provide clients with hints on caching
WCF Default: Cache-Control: private
No caching of private results
// Allow client to cache for 5 minutes
outResponse.Headers.Add("Cache-Control", "300");

39. Conditional GET
Headers used by clients to save bandwidth if they hold cached data
If-Modified-Since: (Date)
Return the data only if it has been modified since (Date)

40. Conditional GET If-None-Matches: (Etag)
Return the data only if there are no records matching this tag
If the data exists but has not been modified return 304 “Not Modified”
The server still has to verify that the resource exists and that it has not changed

41. Supporting If-Modified-Since
Your data should have a LastModified value
Update it whenever the data is written
// Set the headers
outResponse.LastModified = customerData.LastModified;

42. Supporting If-None-Matches
Your data should have a row version
This data is returned in an Etag header as an opaque string
// Set the headers
outResponse.ETag = customerData.ETag.ToString();

43. Conditional GET Check Not Modified? Suppress body
private static void CheckModifiedSince(
IncomingWebRequestContext inRequest,
OutgoingWebResponseContext outResponse,
CustomerData customerData) {
// Get the If-Modified-Since header
DateTime? modifiedSince = GetIfModifiedSince(inRequest);
// Check for conditional get If-Modified-Since
if (modifiedSince != null)
if (customerData.LastModified <= modifiedSince)
outResponse.SuppressEntityBody = true;
outResponse.StatusCode = HttpStatusCode.NotModified; }
Not Modified?
Suppress body
Return 304 “Not Modified”

44. GET Response 200 OK 304 Not Modified 400 Bad Request 404 Not Found
GET successful
304 Not Modified
Conditional GET did not find new data
400 Bad Request
Problem with the request of some kind
404 Not Found
Resource was not found
500 Internal Server Error
Everything else

45. “You can use it to create resources underneath a parent resource and you can use it to append extra data onto the current state of a resource.”
- RESTful Web Services
http post

46. HTTP POST POST is ambiguously defined in the HTTP spec
POST is the second most used RESTful verb
Often referred to as POST(a) for “Append”
Posting to a collection means to append to that collection
Allows the server to determine the ultimate URI

47. HTTP POST Problem Solutions How to detect duplicate POST requests?
Use PUT (it’s Idempotent by nature)
Schemes involving handshaking of some kind between the client and server
Client generated identifier for POST

48. POST to Customers Appends a new customer to the collection Issues
Security – Are you allowed to create a customer?
Idempotency – is this a duplicate POST request?
REST API
SOAP API
(POST)
CustomerData AppendCustomer(CustomerData customer);

49. POST Example public CustomerData AppendCustomer(CustomerData customer){
OutgoingWebResponseContext outResponse = WebOperationContext.Current.OutgoingResponse;
try
CustomerData newCustomer = CustomersCollection.AppendCustomer(customer);
if (newCustomer.CustomerID != 0)
outResponse.SetStatusAsCreated(
BuildResourceUri("customer", newCustomer.CustomerID.ToString())); }
return newCustomer;
catch (CustomerRowIDExistsException)
outResponse.StatusCode = HttpStatusCode.Conflict;
outResponse.StatusDescription = "RowID exists, it must be unique";
return null;
catch (Exception ex)
Log.Write(ex);
throw;

50. POST(a) Response 200 OK 400 Bad Request 409 Conflict
POST successful
400 Bad Request
Problem with the request of some kind
409 Conflict
Resource already exists
500 Internal Server Error
Everything else

51. Testing POST Methods Fiddler – http://www.fiddler2.com HTTP proxy
Use machine name instead of localhost in URI
IIS hosting helps with this
Build a request
Drag a GET request to the Request Builder
Open a GET in Visual Studio for easy formatting of XML
Set the Request type to POST
Set the request body to valid XML
Set the Content-Type: text/xml

52. PUT is an idempotent way to create / update a resource
http PUT

53. HTTP PUT Creates or Updates the resource Idempotent by design
Completely replaces whatever was there before with the new content
Update the cache with new resource
Idempotent by design
Creating or Updating record 123 multiple times should result in the same value
Do NOT do some kind of relative calculation

54. PUT and IDs
If you can allow the client to define an ID within a context that is unique, PUT can insert, otherwise PUT is used to update resources
REST API
SOAP API
Note: the first arg comes from the URI, the customer data comes from the request body
(PUT)
CustomerData PutCustomer(string customerId,
CustomerData customer);

55. PUT Response 200 OK 201 Created 400 Bad Request 404 Not Found
Update successful
201 Created
Insert Successful
400 Bad Request
Problem with the request of some kind
404 Not Found
Resource to update was not found
500 Internal Server Error
Everything else

56. DELETE is for uh... well... um... deleting things
http DELETE

57. DELETE Used to delete a resource Issues
Security – can you delete a resource
Cache – need to remove it from the server cache

58. DELETE Response 200 OK 400 Bad Request 404 Not Found
Delete successful
400 Bad Request
Problem with the request of some kind
404 Not Found
Resource to delete was not found
500 Internal Server Error
Everything else

59. URI Mapping URI Method Maps To api/customer GET api.svc/customer POST
api/customer/{ID}
api.svc/customer/{ID}
DELETE
PUT
HEAD

60. UriMapper HTTP Module RESTful people do not like ugly URIs
ScottGu has Many ways to rewrite URIs
HttpModules can rewrite the URIs as they come in
Jon Flanders blog
Using WCF WebHttpBinding and WebGet with nicer Urls
Modified it a bit to support my scenario

61. Gotchca!
I installed my HttpModule in web.config under <system.web><httpModules>
Not working
Searched blogs to find out that for IIS 7 you must install under <system.webServer><modules>
If your HttpModule does not rewrite the URL correctly you will get 404 errors and have a hard time understanding why

62. Content Negotiation Trend is toward an extension syntax
Unfortunately you must specify the response format in the WebGet, WebInvoke attribute
You can dynamically choose your format by making your service return a stream and then serializing your content directly to the stream

63. Two Services apixml.svc for XML apijson.svc for JSON
UriMapper code looks for an extension on the resource and maps it to the appropriate service
default is XML
2 .SVC files means two classes that implement 2 different contracts

64. Class Diagram

65. URI Mapping URI Method Maps To api/customer GET apixml.svc/customer
POST
api/customer/{ID}
apixml.svc/customer/{ID}
DELETE
PUT
HEAD
api/customer.json
apijson.svc/customer
api/customer/{ID}.json
apijson.svc/customer/{ID}

66. Content Negotiation Demo

67. Consuming a RESTful Service
Use WCF or HttpWebRequest
Need a ServiceContract interface
Copy from service
Build from scratch
Build UriTemplates that will match up to the service

68. Data Contract Schema Export Schema from Assembly
svcutil foo.dll /dconly
Generate data contracts from xsd files
svcutil *.xsd /dconly

69. a scope to access the context
Using WCF on the Client
public CustomerData GetCustomer(string customerId,
Guid? eTag,
DateTime? modifiedSince) {
using (var factory = new
WebChannelFactory<IAdventureWorksServiceXml>("AdventureWorks"))
IAdventureWorksServiceXml service =
factory.CreateChannel();
using (OperationContextScope scope =
new OperationContextScope( (IContextChannel)service))
OutgoingWebRequestContext request =
WebOperationContext.Current.OutgoingRequest;
if (eTag != null)
request.IfNoneMatch = eTag.ToString();
if (modifiedSince != null)
DateTimeFormatInfo formatInfo =
CultureInfo.InvariantCulture.DateTimeFormat;
// RFC1123Pattern
request.IfModifiedSince =
modifiedSince.Value.ToString("r", formatInfo); }
return service.GetCustomer(customerId);
You must create
a scope to access the context

70. Summary RESTful services extend the reach of HTTP to your SOA
RESTful design is harder than you might think
Implementation has some tricky issues to overcome