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 of course is a GitHub repo you can folk 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 ins’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.
Add new project in Visual Studio 2013/2015: File -> New -> Project -> ASP.NET Web Application -> Empty Template
Then 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:
<httpErrors errorMode="Custom" existingResponse="PassThrough" /> <!-- This forces errors to the Owin pipeline -->
Add a class to the root of the project called Startup.cs and add the following code:
That’s it add an 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.