Enjoying the Move from WCF to the

ASP.NET Web APIW. Kevin Hazzard

An API should be…

• Discoverable

• Intuitive

• Standards-based

• Economical

• Adaptive

• Fun

Richardson Maturity Model

martinfowler.com/articles/richardsonMaturityModel.html

The ASMX Experience

• Simple publication model

• HTTP for transport only

• Slow serialization

• Tightly integration with

ASP.NET and IIS

• Difficult to test

• Encourages the RPC

(swamp of POX) model

• A simple, Level 0

experience

Level 3

Level 2

Level 1

Level 0

The WCF Experience

• Complex publication model

• Highly configurable transports

• Better serialization

• Well-integrated with IIS

• Also easy to self-host

• Very rich metadata

• Difficult to test

• Rich data contracts hint at

resource-orientation

• A highly-adaptable but

complex Level 1 experience

Level 3

Level 2

Level 1

Level 0

From StackOverflow.com

“I am totally confused between WCF and

ASMX web services. I have used a lot of web

services in my earlier stage and now there is

this new thing introduced called WCF. I can

still create WCF that function as a web

service. I think there will be more stuff in

WCF. Can anyone provide me any article or

difference between WCF and Web services

such as which one to use and when?”

Result: many developers stayed with ASMX.

Cessna 172 v. Boeing 747

ASMX WCF

The Web API Experience

• Tightly coupled to HTTP

• Content negotiation

• Open-ended formatting

• No reliance on a platform

• (Almost) no metadata

• Solid resource-orientation

• Easy to test

• A simple, HTTP-centric, Level 2 experience with nascent hypermedia support

Level 3

Level 2

Level 1

Level 0

H A T E O A S

Hypermedia As

The Engine Of

Application State

H A T E O A S

Today, would you design a

web application that requires

proprietary or native, third-

party plug-ins

to run inside the

web browser?

Web API Architecture

Web API Processing Architecture

Htt

pR

eq

ue

stM

es

sa

ge

Http

Re

sp

on

se

Me

ss

ag

e

HTTP Request

GET /index.html HTTP/1.1

Accept: text/html

Accept-Encoding: gzip, deflate

Accept-Language: en-US

User-Agent: Mozilla/5.0

Connection: Keep-Alive

HttpRequestMessage

Method

Headers

Content

GET /index.html HTTP/1.1

Accept: text/html

Accept-Encoding: gzip, deflate

Accept-Language: en-US

User-Agent: Mozilla/5.0

Connection: Keep-Alive

RequestUri

Extensions, etc.

• CreateErrorResponse – many overloads

• CreateResponse – many overloads

• GetClientCertificate

• GetProperty<T>

• GetQueryNameValuePairs

• GetUrlHelper

• Properties

Most are in System.Net.Http.dll.

HTTP Response

HTTP/1.1 200 OK

Cache-Control: private, max-age=0

Content-Type: application/json

Vary: Accept-Encoding

Date: Thu, 31 Dec 2015 23:59:59 GMT

Content-Length: 412

Connection: keep-alive

Set-Cookie: XYZ=123; domain=.me.com; path=/

[{"id" : 811, "First" : “Kevin”, ...

HttpResponseMessage

Headers

Content

HTTP/1.1 200 OK

Cache-Control: private, max-age=0

Content-Type: application/json

Vary: Accept-Encoding

Date: Thu, 31 Dec 2015 23:59:59 GMT

Content-Length: 412

Connection: keep-alive

Set-Cookie: XYZ=123; domain=.me.com; path=/

[{"id" : 811, "First" : “Kevin”, ...

StatusCode

Response Extras

• ReasonString – string

• IsSuccessStatusCode - bool

• RequestMessage – HttpRequestMessage

Important Attributes

o HttpGet

o HttpPost

o HttpPut

o HttpPatch

o HttpDelete

o HttpHead

o HttpOptions

o AcceptVerbs

o Authorize

o AllowAnonymous

o NonAction

o FromBody

o FromUri

o Queryable

Example OneCreate a Simple Controller to Fetch Person Entities

Add OData Query Syntax Support

Constrain the Queryable Interface

Example One Summary

• Implement a basic controller with actions

• Demonstrate controller selection by convention

• Discuss controller selection by attribution

• Implement OData query parameters and

demonstrate

• Discuss Queryable attribute

Where’s my metadata?

• Web API publishes metadata!

• See Yao’s blog:

http://blogs.msdn.com/b/yaohuang1

• IApiExplorer research has yieldedo Web API Help Pages

o Web API Test Client

Example TwoAdd WebApiTestClient to the Project and Configure

Turn Documentation Comments on and Configure

Cross-Cutting Concerns

HttpMessageHandler class:

protected abstract

Task<HttpResponseMessage>

SendAsync(

HttpRequestMessage request,

CancellationToken token);

DelegatingHandler

Derives from

HttpMessageHandler

Chains handlers together

in the order you

add them

Chained Handlers

Server

SendAsync SendAsync SendAsync

Example ThreeImplement an Authorization Key Handler

Example Three Summary

• Implement an application key handler

• Discuss the invocation of the InnerHandler

• Demonstrate the creation and return of an error

response

• Discuss why throwing exceptions will always return

an HTTP 500 (Internal Server Error) result

• Demonstrate using the request object to create the

error response instead

• Attach the handler to the pipeline

• Debug with Help & Test

Security Tips

• Tunnel via SSL when possible

• Use Thinktecture IdentityModel for authentication

• Use [Authorize] and [AllowAnonymous] for

authentication

• For CORS support:o ThinkTecture.IdentityModel

o Microsoft ASP.NET Web API Cross-Origin Support (Beta)

• Think PAINT

Self-Hosting

Microsoft ASP.NET Web API Self Host

http://topshelf-project.com

http://owin.org

https://katanaproject.codeplex.com

Issues and Missing Stuff

Caching (Safety)

Idempotence

Transaction Enlistment

Concurrency and

Instancing

Message Encryption

One-way APIs

Recommendations

• Focus on documentation, media types and

hyperlinking

• Use help pages and the WebApiTestClient

• Define cross-cutting concerns and use message

handlers

• Consider the Katana Project and Open Web

Interface for .NET (OWIN) for self-hosting

• Use the ThinkTecture.Identity Model

• Make testing a central theme in your API

development because it’s so easy

Contacting Kevin

@KevinHazzard

blogs.captechconsulting.com

manning.com/hazzard