So you’ll probably be using IIS to run your WebAPI apps, but you really don’t need to. WebAPI ships with a class which starts a web server handling WebAPI requests, in System.Web.Http.SelfHost..dll — HttpSelfHostServer.

Now, this is really interesting, for two reasons.

1) You can spin up a new server, run some tests against it, and shut it down. That means you can test all your HTTP traffic without having to set up a development server. I struggled with this all last week — how do you write a test to prove all your HTTP code is working, but not require all your developers to set up a web server like http://localhost:3000/myapp just so that you’ve got somewhere to act as an endpoint for calls? This short-lived server becomes your endpoint for the lifecycle of the tests.

2) It allows you to create a host outside IIS, on a non-server machine. For instance, imagine you were writing a document search application. It has a front end written in Windows Forms, and the backend is written in WebAPI. When you start the app, it starts an HTTP server at http://localhost:1234/mydocumentsearch. The front end loads its data by making GET requests to that server, and saves changes by POSTS and PUTS and DELETES. Now let’s say you want to search the corporate network using the same app. It would be simple to change the URI to http://corporateserver/documentsearch and now the same app, with no code changes, has become a corporate intranet-based application. Change it again to http://www.internetdocuments.com/search and it’s now an internet-enabled cloud-whatsit buzzword-filled bundle of awesome. And you don’t need to recompile to switch between these seriously different modes.

This approach says — code for HTTP first, and in fact only code for HTTP. You don’t need any other kind of public API. You don’t need an API that you compile into your app, but instead you really code in separate tiers communicating through HTTP. You can now code everything as if it were cloud-enabled, and then just switch to the cloud when you’re ready.

For me, it’s the testing scenario that’ll be most useful in the short term, but the other one is making me think about API design. After all, there are now even database engines (like CouchDb) which only offer HTTP/JSON interfaces. HTTP has become a universal communication mechanism. Will this become the widespread pattern of the future?

Search NuGet for the WebAPI test client (Search `testclient` and make sure you allow prerelease software) and you’ll add a really rather sexy feature to your site. It’s an automatic help generator for your site, so that if you go to `http://myapp/help` you get an HTML site allowing you to see all your URLs, their formats, what methods and parameters they take. It also allows you to execute the methods, giving you an in-browser form for building requests. In a recent project, I built something similar — I recognised the need — but this is just miles ahead of mine.

This is something I’ve only seen in a demo, but it looks like a very sweet addition to your site, at least in debug mode. It means you should be able to write a method then see it work in the browser without having to build a ‘proper’ client for it. Unlike the familiar testing pattern where you new up a controller and execute its methods, this tests the whole architecture of your site, including all the serious bits you need to test about model binding, error handling, etc.

Typically, a WebAPI method might look like this;


public Project Get(int id)
{
return this.repo.GetProject(id);
}


And what we’re seeing here is a method that returns a Project object — or rather, a Project object that is later converted into a JSON object…

So it may be that you need to do a whole lot more — say, in sniffing HTTP headers for a particular purpose, or returning more interesting things in the response. So here’s how you would alter the above method;


public HttpResponseMessage Get(HttpRequestMessage request)
{
if (request.Headers[...])
...
}


And now you’re able to do anything you like with the request — you’ve got full control if you need it. It’s the ‘escape hatch’ out of the sometimes-too-helpful set of conventions. Not something for everyday, but something to use when all else fails, I think.

This was by far the most pragmatically useful of the sessions so far. We’ve just started using WebAPI and it’s clear that there’s loads more to it than we’re using. Of vital importance to me was an understanding of just how the magic works.

It seems to me that when you get into a new technology, it’s always pretty fraught. Or it should be, because you should be always asking yourself, ‘Am I doing this the right way? Is this the way that a pro would do it, or is it the way an amateur hacker would do it?’ Christian Weyer helped point me down the right path. Luckily, much of the things we’ve been doing are right, and the rest are easy to address.

First up, then — what is WebAPI and why do we care?

Well, WebAPI is a way to build HTTP APIs for your services. The HTTP API is designed to live between the client app — be it web page, console app, Windows Forms app, or iOS app — and provide all the business logic and database logic.

There are a raft of tips, so rather than smashing them all into one big blog post, I’m going to post things one at a time. I’ll tag them all `WebAPI` and `DevWeek` so you can search them out more easily.