@filip_woj

Unleash

the power of HTTP

with ASP.NET Web API

@filip_woj

@filip_woj

www.strathweb.com

www.arcmedia.ch

@filip_woj

HTTP

@filip_woj

Trying to build a good API

@filip_woj

What is ASP.NET Web API?

New Microsoft framework (August 2012, Version 2

October 2013) for building HTTP services & applications

Aimed at simplyfing and standardizing HTTP area on the

MS stack (see: WCF / ASMX / MVC / HttpHandlers)

HTTP as a fully fledged *application* protocol

Async from top-to-bottom

Open source!

@filip_woj

“ASP.NET” “Web API”

The name creates lots of misconceptions

“ASP.NET”:

it doesn't require neither ASP.NET, nor IIS to run

“Web API”:

it's an HTTP framework, that can do much more than "just" API

@filip_woj

How can it work without ASP.NET/IIS?

Web hosting:

ASP.NET & IIS

Self hosting: (using WCF hardened core)

WPF

Windows service

console app, any other .NET app

OWIN (i.e. Katana)

Memory hosting: whole pipeline running in memory

@filip_woj

Demo: first API – self hosted

@filip_woj

New HTTP object model

Strongly typed HttpResponseMessage

Strongly typed HttpRequestMessage

Strongly typed Headers

Strongly typed HttpContent

No more “angle brackets coding” & magic strings

Asynchronous API

Client-server symmetry

HTTP status codes

@filip_woj

HTTP status codes

1xx – Informational

2xx – Successful

3xx – Redirection

4xx – Error on the client side

5xx – Error on the server side

@filip_woj

Demo: Created 201 / BadRequest 400

@filip_woj

HTTP headers – request

Request headers (selected)

Accept, Accept-Language, Accept-Encoding

Authorization, Cache-Control, Range

If-Match, If-Modified-Since, If-Range

Content headers (selected)

Allow, Content-Encoding, Content-Language

Content-Length, Content-Type, Expires

Last-Modified

@filip_woj

HTTP headers – response

Response headers (selected)

Accept-Ranges, Connection

Cache-control, Date, Etag

RetryAfter, Warning, Location

Content headers (selected)

Allow, Content-Encoding, Content-Language

Content-Length, Content-Type, Expires

Last-Modified

@filip_woj

RPC

/api/GetTeams

/api/GetTeam?id=1

/api/GetPlayersByTeam?id=1

/api/AddTeam

/api/UpdateTeam

/api/UpdateTeam?id=1&name=”Leafs”

/api/DeleteTeam?id=1

From: presentation by @alexbeletsky

@filip_woj

HTTP verbs

Represent core operations on a resource:

- GET: read, cachable, retreives a resource

- POST: non-cacheable, creates a resource

- PUT: updates a resource, safe to call multiple times

- DELETE: deletes a resource, safe to call multiple times

Can also use others i.e. PATCH (partial update of a

resource)

@filip_woj

RESTful

GET /api/teams

GET /api/teams/1

GET /api/teams/1/players

POST /api/teams

PUT /api/teams/1

DELETE /api/teams/1

@filip_woj

Much better

@filip_woj

Controllers

Represent your API resources

Similar as in MVC

Routing engine determines which controller to use

Web API 2 introduces attribute routing

Supports nested resources

@filip_woj

Dispatching actions

By default HTTP verb based (RESTful)

Actions matched:

by prefix (i.e. GetAll, GetById) or

by action attribute (i.e. [HttpPost])

Can be changed to action based (RPC style)

@filip_woj

Don’t be scared of REST

@filip_woj

Content negotiation

Dynamically deciding the media type

Same data can be represented in various formats:

- JSON

– XML

– CSV

– binary

– anything to what your data can be serialized/deserialized from

In Web API done with MediaTypeFormatters

@filip_woj

Content negotiation in Web API

Web API uses the following precedence:

1. MediaTypeMapping

/api/resource.json, /api/resource?format=json

2. Accept headers

Accept: application/json

3. Content type header

Content-Type: text/xml

4. MediaTypeFormatter order & check whether a formatter can

serialize/deserialize a given type

@filip_woj

Demo: Not Acceptable 406

@filip_woj

Extending content negotiation

Very easy, some examples:

- BSON (binary JSON)

- ServiceStack.Text (instead of JSON.NET)

- MessagePack

- Mobi (returning ebook!)

- RSS/Atom

- Supporting Razor views (text/html)

@filip_woj

Client-server symmetry

By: Henrik Frystyk Nielsen

Message handlers can run on server and on the client

HttpServer is a message handler itself

Sample Handler

@filip_woj

Demo: Memory hosted

@filip_woj