Building HTTP services for modern client apps Filip Wojcieszyn

@filip_woj www.strathweb.com www.arcmedia.ch

HTTP

Everywhere! Source: Cisco, 2013, http://newsroom.cisco.com/feature-content?type=webcontent&articleId=1208342

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

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

ASP.NET WEB API

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

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

“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

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.

Building an API

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

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

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

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

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

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

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); }

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

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

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

Media types

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

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)

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

OData

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

Extras

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 http://www.myget.org/F/aspnetwebstacknightly/

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.