Upload
ngothuy
View
215
Download
2
Embed Size (px)
Citation preview
1
Copyright © Brian Noyes 2013
www.solliance.net
Designing RESTful Services with ASP.NET Web API
Brian Noyes
CTO, Solliance Inc.
www.solliance.net
About Brian Noyes
CTO, Solliancewww.solliance.net
Microsoft Regional Director
Microsoft MVP
Pluralsight authorwww.pluralsight.com
www.solliance.net
t
@briannoyes
http://briannoyes.net
Web API Insider, Windows Azure Insider,Window Store App Insider, C#/VB Insider
2
Copyright © Brian Noyes 2013
Agenda
• ASP.NET Web API Overview
• REST Overview
• Developing Web APIs and RESTful services
• Consuming Web APIs
ASP.NET Web API
• New platform for building HTTP web services (Web APIs)
• Built on top of ASP.NET MVC 4 framework• Released with .NET 4.5
• Compatible with .NET 4.0
• Just another Web Application project sub-type in VS 2013
• Makes it easy to build services for consumption from multi-platform clients
• Simple RPC services
• CRUD services
• REST services
• OData services
3
Copyright © Brian Noyes 2013
ASP.NET Web API
• Services are Controllers• ApiController class
• Leverages MVC features• Routing
• Model binding
• Action filters
ASP.NET Web API
• Convention over configuration• Maps URIs to controllers
• Maps HTTP verbs to methods / actions
• Maps URI / query string parameters to method parameters
HTTP/1.1
Request
GET http://localhost:2112/api/Customers/ALFKI?includeOrders=true HTTP/1.1
User-Agent: Fiddler
Host: localhost:2112
public class CustomersController : ApiController
{
public Customer GetCustomer(string id, bool includeOrders)
{ ... }
}
4
Copyright © Brian Noyes 2013
ASP.NET Web API
• Content negotiation• Based off HTTP Accept / Content-Type headers
• JSON / XML formatters out of the box
• OData formatter through NuGet
• Can plug in custom formatters
Request
GET http://localhost:2112/api/Customers/ALFKI HTTP/1.1
User-Agent: Fiddler
Host: localhost:2112
Accept: application/json
Response
HTTP/1.1 200 OK ...
Content-Type: application/json; charset=utf-8
Content-Length: 206
{"CustomerID":"ALFKI","CompanyName":"Alfreds Futterkiste"}
ASP.NET Web API Configuration
• No config file settings needed
• HttpConfiguration class• Associated with the ASP.NET web application instance
• Accessible from Global.asax code behind
• Calls WebApiConfig.Register
• Defaults are good enough for basic Web APIs
• Can plug in formatters, filters, message handlers and other custom extensibility objects through this class
public static class WebApiConfig
{
public static void Register(HttpConfiguration config)
{
config.Routes.MapHttpRoute(
name: "DefaultApi",
routeTemplate: "api/{controller}/{id}",
defaults: new { id = RouteParameter.Optional }
);
}
}
5
Copyright © Brian Noyes 2013
REST
• REpresentational State Transfer
• Focus on Resources and Representations instead of remote objects and operations
• REST is an architectural style, SOAP is a protocol
• Based on Ph.D. thesis: Roy Fielding
• REST fully embraces HTTPURI
HTTP Verb
HTTP HeadersHTTP Headers
Service address
Resource
Parameters
Operation
(POST,GET,PUT,DELETE)
Content Negotiation
Security, Etags, etc.
Payload
Status Codes
Media
Types
Hypermedia
HTTP Body
Web APIs vs REST
• Web APIs or Web HTTP services are not necessarily REST services
• REST is defined in terms of a set of architectural constraints
• Formal usage of REST vs common use of REST• Roy Fielding’s thesis
• REST in Practice, Jim Webber et al, http://shop.oreilly.com/product/9780596805838.do
• REST APIs must be HyperText drivenhttp://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
• Building Hypermedia Web APIs with ASP.NET Web APIhttp://msdn.microsoft.com/en-us/magazine/jj883957.aspx
• Building Hypermedia APIs with HTML5 and Nodehttp://shop.oreilly.com/product/0636920020530.do
6
Copyright © Brian Noyes 2013
REST Architectural Constraints
• Client-Server
• Stateless
• Cache
• Layered architecture
• Uniform Interface
• Code On Demand
Uniform Interface
• Identification of resources• URIs
• Manipulation of resources• HTTP Verbs• Representations• URI/Query string parameters• HTTP Status codes / headers
• Self-descriptive messages• Media types
• Hypermedia as the engine of application state (HATEOAS)
• Links identify related resources and available actions on the current resource
• Analogous to a service contract in SOA
7
Copyright © Brian Noyes 2013
Richardson’s Maturity Model
Level 0: POX / RPC
Level 1: URI / Resources
Level 2: HTTP
Level 3: Hypermedia
URI Design
• Service location
• Resource
• Parameters for manipulating the resource
• URL parameters or query string parameters
http://somesite.org/ResourceName/resourceId
http://somesite.org/ResourceName/ChildResource/resourceid/param
http://somesite.org/ResourceName?param1=a¶m2=b
8
Copyright © Brian Noyes 2013
HTTP Services
• URI for service address + operation + parameters
• HTTP protocol • Verbs, headers, caching, status codes
• Content negotiation• Accept / Content-Type headers
• Media types
• HTTP Body• Contains representations of requested resource
Hypermedia-driven services
• Client only knows one URI
• Representations in responses contain hypermedia links• Links to related resources
• Action links to transition the resource to a new state
• Indicate allowable actions (operations) for that client for that resource for that point in time
9
Copyright © Brian Noyes 2013
OData as REST
• Standardized approach to CRUD Web APIs• Query syntax
• Complex filtering, ordering, paging, expanding, and selecting driven by the client
• OData formats
• ATOMPub XML, JSON Light, JSON Verbose
• Supports content negotiation
• Uses hypermedia linking• Relations
• Actions
Consuming REST APIs
• No metadata standard• No code generated proxies
• Theory:• Client only needs to know single root URI
• Reality:• Still need out-of-band information on media types and verbs
10
Copyright © Brian Noyes 2013
Consuming REST / Web APIs in .NET
• Old school• WebClient / HttpWebRequest
• New: HttpClient class• Available in .NET 4 / 4.5 and WinRT
• Async methods for GET, PUT, POST, DELETE
• Supports content negotiation
• Sample pluggable formatters as the server side
• Serializes strongly typed payload objects
Consuming REST/Web APIs in JavaScript
• Jquery, Angular, etc - AJAX• URL
• Method (verb)
• Content Negotiation (Accept/Content-Type headers)
• Handles JSON payloads natively
• Avoid XML
11
Copyright © Brian Noyes 2013
Thank You!
• Building Web API OData Serviceshttp://pluralsight.com/training/courses/TableOfContents?courseName=aspnetwebapi-odata
• Building End-to-End Multi-Client Service Oriented Applicationshttp://pluralsight.com/training/Courses/TableOfContents/building-multi-client-end-to-end-service-oriented-applications
• Roy Fielding Thesis:http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
• RESTful Web APIshttp://shop.oreilly.com/product/0636920028468.do
• Designing Evolvable Web APIs with ASP.NEThttp://chimera.labs.oreilly.com/books/1234000001708
• REST in Practice, Jim Webber et al, http://shop.oreilly.com/product/9780596805838.do
• REST APIs Must Be Hypermedia Drivenhttp://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
• Building Hypermedia Web APIs with ASP.NET Web APIhttp://msdn.microsoft.com/en-us/magazine/jj883957.aspx
www.solliance.net
t
@briannoyes
http://briannoyes.net