REST and the WCF Web API

Getting started with REST services and the WCF Web API

Maurice de Beijer

Objectives

• What are REST services• Why REST instead of SOAP• The WCF Web API framework

• The next webinar on the 25th of October is about creating HTML5/JavaScript clients for REST services

What are REST services

• Representational State Transfer• A way of creating web services

– Not using the WS-* SOAP specifications

• All about resources– Not about calling functions, RPC

• Embraces HTTP– Not just a way of getting data across the wire

• Leverages the structure of the Internet– URLS– MIME Media Types– HTTP Methods– Caching– Security

The origin of REST

• Architectural Styles and the Design of Network-based Software Architectures– By Roy Thomas Fielding– Chapter 5

• One of the authors of the HTTP specification

Why are REST services popular

• Almost every platform supports consuming them– All you need is an HTTP client stack

• Many services are build around resources– CRUD style

• Enables very scalable services– Build around the technology that powers the Internet

The WCF Web API framework

• On CodePlex– http://wcf.codeplex.com/wikipage?title=WCF%20HTTP

• Use NuGet from within Visual Studio 2010– http://nuget.org/

• Current version 0.5• Much better than the original WCF support for REST

– But doesn’t replace it

The resource URL

• The URL is the key to a resource– http://bookshop.com/books (The collection of books)– http://bookshop.com/books/12345 (An individual book)

• A given URL always returns the same resource– Deleting one resource doesn’t change the URL of another

resource

• But a resource can have multiple URL’s– http://bookshop.com/orders/12345– http://bookshop.com/customers/12345/orders/12345

Different request/response formats

• Uses standard HTTP MIME Media Types– http://www.iana.org/assignments/media-types/index.html

• Content Negotiation– The client specifies a list of acceptable media types– The server chooses the best supported media type to

return

• XML– Good general purpose data format

• JSON– Optimised for usage with JavaScript clients

• Custom formats– Use one of the many IANA types– Define your own

• Normally prefixed with vnd.• Example: application/vnd.wordperfect

HTTP Status codes

• Tell the client application what happened

• Successful 2xx– 200 OK– 201 Resource created

• Redirection 3xx– 301 Moved Permanently

• Client Error 4xx– 400 Bad request– 404 Not found

• Server Error 5xx– 500 Internal Server Error– 503 Service Unavailable

HTTP GET Method

• No side effects– Can retrieve it as often as you like

• Allows for caching– Request may never get to the server– Makes the web as scalable as it is

• Use Accept header to specify the acceptable media type– Multiple types are supported

• Examples:– Accept: application/xml– Accept: application/json– Accept: image/jpeg, image/*; q=0.5

Other HTTP Methods

• POST– Creates new resource– Returns the URL to the created resource

• PUT or PATCH– Replaces/updates resource– Idempotent– PATCH only replaces a part of the resource

• DELETE– Removes resource– Idempotent

Microformats

• Enable a much smarter client application– Embed allowed actions with a resource– Client can update the UI based on the resource

• OData is a good example– Based on AtomPub– http://www.odata.org

• Roll your own– Or reuse an existing one from IANA

• Set the content-type– Use your own application/vnd.xxx

Rest is not perfect

• No metadata– Little tooling in Visual Studio 2010

• It’s harder than it seems– There is no official REST standard– There are many strong opinions about what is REST and

what is not

Usefull resources

• Essential Windows Communication Foundation 4 Training– http://www.develop.com/training-course/windows-communi

cation-foundation-wcf

• Hypertext Transfer Protocol -- HTTP/1.1– http://tools.ietf.org/html/rfc2616

• The Atom Syndication Format– http://tools.ietf.org/html/rfc4287

• The Atom Publishing Protocol– http://tools.ietf.org/html/rfc5023

• Open Data Protocol (OData)– http://www.odata.org

• WCF Web API Contrib– http://webapicontrib.codeplex.com

• Fiddler– http://www.fiddler2.com

Summary

• REST is all about resources– CRUD actions

• REST embraces HTTP and the web– HTTP isn’t just a means of moving bits

• REST services are a good way to build scalable services– Build on the infrastructure of the web

• REST allows for very flexible services– You control every part of the message