An introduction to the ASP.NET Web API with a focus on RESTful design.

1. The ASP.NET Web
API for Beginners
W. Kevin Hazzard

2. Richardson Maturity Model
martinfowler.com/articles/richardsonMaturityModel.html

3. The Web API Experience
• Solid resource-orientation
• HTTP method support
• Content negotiation
• Open-ended formatting
• Model-binding
• Minimal platform
dependencies
• Test friendly
Level 3
Level 2
Level 1
Level 0

4. H A T E O A S
Hypermedia As
The Engine Of
Application State
H A T E O A S

5. Web API Architecture

6. Web API Processing Architecture
HttpRequestMessage
HttpResponseMessag
e

7. 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

8. HttpRequestMessage
• In System.Net.Http namespace
• Properties:
o Content – HttpContent
o Headers – HttpRequestHeaders
o Method – HttpMethod
o Properties – IDictionary<string, object>
o RequestUri – Uri

9. Request Extensions
• CreateErrorResponse – many overloads
• CreateResponse – many overloads
• GetClientCertificate
• GetProperty<T>
• GetQueryNameValuePairs
• GetUrlHelper
These are in System.Net.Http.dll.

10. HTTP Response
HTTP/1.1 200 OK
Cache-Control: private, max-age=0
Content-Type: text/html; charset=utf-8
Vary: Accept-Encoding
Date: Thu, 31 Dec 2015 23:59:59 GMT
Content-Length: 41309
Connection: keep-alive
Set-Cookie: XYZ=123; domain=.me.com; path=/
...

11. HttpResponseMessage
• In System.Net.Http namespace
• Properties:
o Content – HttpContent
o Headers – HttpResponseHeaders
o IsSuccessStatusCode – bool
o ReasonString – string
o RequestMessage – HttpRequestMessage
o StatusCode – HttpStatusCode

12. Key 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

13. Example One
Create a Simple Controller to Fetch Person Entities
Add OData Query Syntax Support

14. Example One Summary
• Implement a basic controller with a actions
• Demonstrate controller selection by convention
• Discuss controller selection by attribution
• Implement OData query parameters and
demonstrate

15. Example Two
Add WebApiTestClient to the Project and Configure
Turn Documentation Comments on and Configure

16. Cross-Cutting Concerns
HttpMessageHandler class:
protected abstract
Task<HttpResponseMessage>
SendAsync(
HttpRequestMessage request,
CancellationToken token);

17. DelegatingHandler
Derives from
HttpMessageHandler
Chains handlers together
in the order you
add them

18. Chained Handlers
Server
SendAsync SendAsync SendAsync

19. Example Three
Implement an Authorization Key Handler

20. 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

21. Possible Uses
• Implementing a cache manager
• Implementing an AAA scheme
• Capturing pay-per-call data
• Recording statistics
• Logging and tracing
• Inserting custom request and response headers
• Performing message compression or encryption
• Transforming messages

22. Testing Web API
• Faking context with ASMX and WCF is difficult
• Too many platform dependencies
o ASP.NET produces an HttpContext
o WFC produces an OperationContext
• Typically requires a running host

23. Example Four
Add Tests

24. Example Four Summary
• Add test fixtures
• Demonstrate Arrange, Act, Assert pattern
• Call controller action without HttpRequestMethod
• Call controller action with HttpRequestMethod

25. Contacting Kevin
wkhazzard@gmail.com
@KevinHazzard
blogs.captechconsulting.com
manning.com/hazzard