Download Session Slides - DevIntersection.com

DEVintersection

Session AS06


Designing
RESTful

Services with ASP.NET
Web API

Brian Noyes

CTO, Solliance (
www.solliance.net
)

brian.noyes@solliance.net
, @
briannoyes

About Brian Noyes

Solliance (
www.solliance.net
)

CTO

Microsoft Regional Director

Microsoft MVP

Pluralsight

author

www.pluralsight.com

t

e

brian.noyes@solliance.net

@
briannoyes

http://briannoyes.net

Web API Insider, Windows Azure Insider,

Window Store App Insider, C#/VB Insider

3

©
DEVintersection
. All rights reserved.

http://www.DEVintersection.com

Agenda


ASP.NET Web API Overview


REST Overview


Developing Web APIs and
RESTful

services


Consuming Web APIs


4

©
DEVintersection
. All rights reserved.

http://www.DEVintersection.com

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

5

©
DEVintersection
. All rights reserved.

http://www.DEVintersection.com

ASP.NET Web API


Services are Controllers


ApiController

class


Leverages MVC features


Routing


Model binding


Action filters


6

©
DEVintersection
. All rights reserved.

http://www.DEVintersection.com

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


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
)


{ ...

}

}


7

©
DEVintersection
. All rights reserved.

http://www.DEVintersection.com

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
"}


8

©
DEVintersection
. All rights reserved.

http://www.DEVintersection.com

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

}


);


}

}

9

©
DEVintersection
. All rights reserved.

http://www.DEVintersection.com

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 HTTP


URI

HTTP Verb

HTTP Headers

Service address

Resource

Parameters

Operation

(POST,GET,PUT,DELETE)

Content Negotiation

Security,
Etags
, etc.

Payload

Status Codes

Media

Types

Hypermedia

HTTP Body

10

©
DEVintersection
. All rights reserved.

http://www.DEVintersection.com

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

driven

http://roy.gbiv.com/untangled/2008/rest
-
apis
-
must
-
be
-
hypertext
-
driven


Building
Hypermedia Web APIs with ASP.NET Web API

http://
msdn.microsoft.com/en
-
us/magazine/jj883957.aspx



Building
Hypermedia APIs with HTML5 and
Node

http
://
shop.oreilly.com/product/0636920020530.do

11

©
DEVintersection
. All rights reserved.

http://www.DEVintersection.com

REST Architectural Constraints


Client
-
Server


Stateless


Cache


Layered architecture


Uniform Interface


Code On Demand

12

©
DEVintersection
. All rights reserved.

http://www.DEVintersection.com

Uniform Interface


Identification of resources


URIs


Manipulation of resources


HTTP Verbs


Representations


URI/Query string parameters


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

Richardson’s Maturity Model

Level 0: POX / RPC

Level 1: URI / Resources

Level 2: HTTP

Level 3: Hypermedia

14

©
DEVintersection
. All rights reserved.

http://www.DEVintersection.com

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&param2=b

15

©
DEVintersection
. All rights reserved.

http://www.DEVintersection.com

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

16

©
DEVintersection
. All rights reserved.

http://www.DEVintersection.com

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

17

©
DEVintersection
. All rights reserved.

http://www.DEVintersection.com

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

18

©
DEVintersection
. All rights reserved.

http://www.DEVintersection.com

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

19

©
DEVintersection
. All rights reserved.

http://www.DEVintersection.com

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

20

©
DEVintersection
. All rights reserved.

http://www.DEVintersection.com

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

21

©
DEVintersection
. All rights reserved.

http://www.DEVintersection.com

Thank You!


Building Web API OData Services

http://
pluralsight.com/training/courses/TableOfContents?courseName=aspnetwebapi
-
odata


Building End
-
to
-
End Multi
-
Client Service Oriented Applications

http://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


ASP.NET Web Stack

http://aspnetwebstack.codeplex.com



REST
in Practice, Jim Webber et al,
http://shop.oreilly.com/product/9780596805838.do


REST APIs Must Be Hypermedia Driven

http://
roy.gbiv.com/untangled/2008/rest
-
apis
-
must
-
be
-
hypertext
-
driven


Building Hypermedia Web APIs with ASP.NET Web API

http://msdn.microsoft.com/en
-
us/magazine/jj883957.aspx



www.solliance.net

t

e

brian.noyes@solliance.net

@
briannoyes

http://briannoyes.net

Questions?

Thank you!

Don’t forget to enter your evaluation

of this session using EventBoard!

t

e

brian.noyes@solliance.net

@
briannoyes

http://briannoyes.net