1. Building HTTP services for modern client apps
Filip Wojcieszyn

2. @filip_woj

3. HTTP

4. Everywhere!
Source: Cisco, 2013,

5. What do you need? Maintainability Discoverability Scalability
Versioning, debugging
Discoverability
RESTful routing, straightforward documentation
Scalability
Asynchronous pipeline
Flexibility
Customize all the things

6. ASP.NET Web API overview 10’ Building an API 30’ Media types 10’ Rich querying capabilities 10’

7. ASP.NET WEB API

8. Overview New Microsoft framework.
(August 2012, Version 2 October 2013) for building HTTP services & applications
HTTP as a first class citizen in .NET
- Aimed at simplyfing and standardizing HTTP area on the MS stack (see: WCF / ASMX / MVC / HttpHandlers)
- HTTP as a fully fledged *application* protocol
Open source

9. New HTTP object model Strongly typed HTTP concepts.
HttpRequestMessage, HttpResponseMessage, Headers, HttpContent
No «angle brackets coding» or «magic strings»
Code based configuration only
Symmetry between client and server
Asynchronous APIs

10. “ASP.NET” “Web API” ASP.NET Web API
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

11. Hosting Web. Self hosting. In Memory.
ASP.NET & IIS
Self hosting.
Any .NET application can become a Web API server
In Memory.
Whole pipeline in memory
OWIN (Open Web Interface for .NET).
Decouple web application from the host.

12. Building an API

13. API with ASP.NET Web API Create a controller. Add actions. Add routes.
ApiController, IHttpController
Add actions.
Return models / HttpResponseMessage / IHttpActionResult
Add routes.
Centralized or attribute-based
Use message handlers / filters.
Cross-cutting concerns

14. Controllers Represents a HTTP resource
Doesn’t have to map 1-to-1 to an entity!
ApiController provides lots of helpers
Helps you conform to HTTP standards
Can be loaded from other assemblies
Use IAssembliesResolver

15. Don’t
/api/GetTeams /api/GetTeam?id=1 /api/GetPlayersByTeam?id=1 /api/AddTeam /api/UpdateTeam /api/DeleteTeam?id=1

16. Do
GET /api/teams GET /api/teams/1 GET /api/teams/1/players POST /api/teams PUT /api/teams/1 DELETE /api/teams/1

17. Actions Actions handle HTTP request HTTP verb dispatching (RESTful)
Maps to an incoming HTTP request
HTTP verb dispatching (RESTful)
Actions matched:
- by prefix (GetAll, GetById)
- by action attribute (i.e. [HttpPost])
RPC not encouraged, but supported

18. Actions parameters From URI - primitives From Body - complex types
Int, string etc From querystring or route data
From Body - complex types
Use MediaTypeFormatters
Only one thing can be read from body
Customizable
[FromUri], [FromBody], custom parameter binding

19. Action return Model / void HttpResponseMessage IHttpActionResult
Any CLR type
HttpResponseMessage
Work with HTTP concepts directly
IHttpActionResult
Predefined factories creating HttpResponseMessage
public interface IHttpActionResult {
Task<System.Net.Http.HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken); }

22. Routing Attribute routing (Web Api 2) Centralized Customizable
Easy to enable hierarchical, complex routing.
Centralized
Traditional approach known from ASP.NET
Customizable
Constraints, defaults

23. Message handlers Run first/last in the pipeline
Chained
Raw HttpRequestMessage / HttpResponseMessage
Can short-circuit the response
Cross-cutting concerns
Logging, authentication

24. Message handlers Run first and last in the pipeline
Chained
Raw HttpRequestMessage / HttpResponseMessage
Can short-circuit the response
Cross-cutting concerns
Logging, authentication

25. Media types

26. Content negotiation Determining the media type of a response
Client and server engage in a “negotiation process” I.e. application/json or image/png
Same entity can be represented in various formats
JSON (application/json), XML (text/xml), CSV (text/csv), binary (application/octet-stream) and many more
Part of HTTP spec
RFC 2616, section 12

27. Content negotiation in Web API
1. MediaTypeMapping
/api/resource.json, /api/resource?format=json
2. Accept header
Accept: application/json
3. Content-type header
Content-type: text/xml
4. MediaTypeFormatter order
Can be configured to return 406 (Not acceptable)

28. Content negotiation in Web API
JSON
Uses JSON.NET or DataContractSerializer
XML
Uses DataContractSerializer or XmlSerializer
Pluggable
Many other media types can be supported
Conneg can be run by hand
Using IContentNegotiatior

29. OData

30. OData OData V3 Protocol Expose an endpoint as IQueryable
Atom format / JSON light
Expose an endpoint as IQueryable
Client has great freedom in terms of querying capabilities
$top, $skip, $orderby, $filter
Similar as the correspdonding LINQ operators $expand, $select, $value
Support lazy loading and partial retrieval of entites

31. Extras

32. Extras Document your API easily Logging WebApiContrib
Use the HelpPage functionality or raw IApiExplorer
Logging
See what’s happening inside with ITraceWriter
WebApiContrib
Don’t reinvent the wheel, it’s all there for you!
Try out nightlies

33. 1/18/2019 8:29 AM
© 2013 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries.
The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.
© 2010 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries.
The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.