Download presentation
Published byDarlene Raikes Modified over 10 years ago
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
Similar presentations
© 2024 SlidePlayer.com Inc.
All rights reserved.