Professional ASP.NET Web Api Part 1 – WebApi bootstrap without any bloat using Owin

During this series of posts, I'm going to share with you how I work with WebApi. I'm going to share the steps with you so you understand exactly what is going on and the choices made. There is a GitHub repo you can fork and use in your own projects.

Being a consultant, I have to create REST API's (or as I like to say "RESTish API's"*) a lot, I'm going to show you how I do it. When you create your WebApi project your first instinct might be to select the WebApi project template - I would resist doing it like that.

Not because there is anything wrong with using the templates, because there isn't I've used both the WebApi and MVC templates as learning tools as well as for quick hacks. That said, that's what you should use them for - here are my reasons for saying that:

So much of the config is done for you that it can be difficult to understand what's going on, what if you need to change the config or had a deployment issue would you be confident in making changes?

So many extra packages are added that you probably don't need.
It's not Owin backed.

Getting Started

For IISAdd new project in Visual Studio 2013/2015: File -> New -> Project -> ASP.NET Web Application -> Empty TemplateThen install the following NuGet packages:

PM> Install-Package Microsoft.AspNet.WebApi.Owin

PM> Install-Package Microsoft.Owin.Host.SystemWeb

Adding Microsoft.Owin.Host.SystemWeb allows you to use the Owin interface with System.Web i.e. IIS. If you wanted to Self Host just create your containing project (console app,Azure etc) and only install the Microsoft.AspNet.WebApi.OwinSelfHost NuGet package.

If using IIS (Microsoft.Owin.Host.SystemWeb) you want to remove the ugly IIS error pages. To do this in your web.config <system.webServer> add <httpErrors errorMode="Custom" existingResponse="PassThrough" /> so your web.config looks like:

<system.webServer>
   <httpErrors errorMode="Custom" existingResponse="PassThrough" /> <!-- This forces errors to the Owin pipeline -->
</system.webServer>

Add a class to the root of the project called Startup.cs and add the following code:

public class Startup
{
  public void Configuration(IAppBuilder app)
  {
    var config = new HttpConfiguration();
            
    var jsonSerializerSettings = config.Formatters.JsonFormatter.SerializerSettings;

    //Remove unix epoch date handling, in favor of ISO
    jsonSerializerSettings.Converters.Add(new IsoDateTimeConverter { DateTimeFormat = "yyyy'-'MM'-'dd'T'HH':'mm':'ss.fff" });

    //Remove nulls from payload and save bytes
    jsonSerializerSettings.NullValueHandling = NullValueHandling.Ignore;
    
    // Make json output camelCase
    jsonSerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
    
    // Remove xml this will make json the default and your life easier (unless you really need to support xml)
    config.Formatters.XmlFormatter.SupportedMediaTypes
        .Remove(config.Formatters.XmlFormatter.SupportedMediaTypes.FirstOrDefault(t => t.MediaType == "text/xml"));
      
    config.Formatters.XmlFormatter.SupportedMediaTypes
        .Remove(config.Formatters.XmlFormatter.SupportedMediaTypes.FirstOrDefault(t => t.MediaType == "application/xml"));

    // Attribute routing
    config.MapHttpAttributeRoutes();

    // WebApi
    app.UseWebApi(config);
  }
}

That's it add a ApiController and action, and you're good to go.

Why use OWIN and vNext

I was going to do a write on why we should use Owin, but this stackoverflow question has a great answer. All I would add is that although not exactly the same, the concepts of Middleware transfer well to vNext take a look at IApplicationBuilder.

*Most API's I'm asked to create are not truly RESTful if I was to be academic about it (http://en.wikipedia.org/wiki/HATEOAS for example). So I call them RESTish, they are RESTful enough to be useful without going over the top implementing the whole REST spec for vanity.