How to use ASP.NET Web API in Umbraco 4 & .NET 4.0

Note: this post is over a year old, it's very likely completely outdated and should probably not be used as reference any more. You have been warned. :-)

So, you really like the idea of the ASP.NET Web API and can't wait to use it? But you're using Umbraco 4 and / or Webforms? Good news everybody! It's super easy to use it.

First of all: Umbraco. It has a compiled global.asax out of the box and you can't actually go and extend it. In order to register the routing for the Web API you would normally have to edit the global.asax. Luckily, you can implement this easily using the System.Web.PreApplicationStartMethod.

So in Umbraco I have my Umbraco.Web project which is often completely uncompiled, so it's a Web Site Project instead of a Web Application Project (although I'm changing this). Next to that I usually have a seperate project called CustomerName.Extensions in which I add custom code that is compiled and the DLL ends up in Umbraco's bin folder.

Note: if you want to follow along, ASP.NET MVC 4 should be installed (it includes the Web API) on your machine (not in Umbraco) or you could install the Web API nuget package.

In your (Umbraco) web project, you will also need a reference to Json.NET, again, just install the nuget package.

To start with, I add references to that Extensions project: 

  • System.Web
  • System.Web.Http
  • System.Web.Http.WebHost

Then I add a class to register the API routes on startup, for me it looks like this: 

using System.Linq;
using System.Web.Routing;
using System.Web.Http;
using CustomerName.Extensions;

[assembly: System.Web.PreApplicationStartMethod(typeof(AppStart), "PreStart")]
namespace CustomerName.Extensions
public static class AppStart
public static void PreStart()
name: "DefaultApi",
routeTemplate: "api/{controller}/{id}",
defaults: new { id = RouteParameter.Optional }

To test if the Web API bits work, add a new item to your project, I don't know about VS2010 but in VS2012 you can just find the Web API Controller Class right there.


If you can't pick that one, then just make a new class and have it inherit from ApiController (as pictured above as well).

The default API Controller will give you some methods and you can immediately compile and check it out.

So in my case, I go to: http://mysite.local/api/values and get a lovely XML feed:

C 36x

And.. that's all there is to it!

Sebastiaan Janssen

Dutch guy living in (and loving) Copenhagen, working at Umbraco HQ. Lifehacker, skeptic, music lover, cyclist, developer.


20 comments on this article

Avatar for Pinal Bhatt [] Pinal Bhatt [] | June 28 2012 22:21
Really good call. But one question did you integrated Umbraco 4.7.2 project with MVC4 first before doing these steps?

Avatar for Sebastiaan Janssen Sebastiaan Janssen | June 28 2012 22:25
Thank Pinal! No this was on a pure Umbraco 4.7.0 project, nothing installed beforehand. It will work equally well on any other Webforms project.

Avatar for  Pinal Bhatt [] Pinal Bhatt [] | November 11 2012 12:50
Hi Sebastiaan, This functionality works fine in umbraco 4.9 for me. But what about 4.10 after modifications in request pipelines.

I tried to implement this in U4.10 but not working out.

Thanks & Regards
Pinal Bhatt

Avatar for Sebastiaan Janssen Sebastiaan Janssen | November 11 2012 13:46
@Pinal it seems to work fine for me, although I did have to add ~/api/ to the umbracoReservedPaths (web.config). So if your routes also start with /api/ then try that.

Avatar for Pinal Bhatt [] Pinal Bhatt [] | November 11 2012 13:53
yup... that trick worked. so with U4.10 we need to add ~/api/ to umbracoReservedPaths (web.config).

Thanks a lot.

Avatar for Sebastiaan Janssen Sebastiaan Janssen | November 11 2012 13:56
I'll ask Shannon if this can be fixed in 4.11.0 somehow, we've been talking about a similar scenario before so I think he might be able to make it work again.

Also, for your information, we're now offering a new way to register routes that might be handier for you, read about it here:

Avatar for Pinal Bhatt [] Pinal Bhatt [] | November 11 2012 13:58
Was also able to run this by overriding OnApplicationStarted in my new custom global.asax after inheriting it from Umbraco.Web.UmbracoApplication instead of using System.Web.PreApplicationStartMethod.

Once again thanks a lot for this wonderful concept.

Avatar for Sebastiaan Janssen Sebastiaan Janssen | November 11 2012 14:00
Hmmm, I'm not sure you were intended to do that. Be advised that we're recommending the method mentioned in that issue instead, so you might want to rewrite it a tiny bit. :-)

Avatar for Pinal Bhatt [] Pinal Bhatt [] | November 11 2012 14:09
sorry but could not get you.
Which method you suggest: Using System.Web.PreApplicationStartMethod or overriding OnApplicationStarted?

Avatar for Sebastiaan Janssen Sebastiaan Janssen | November 12 2012 08:33
Look at the issue I posted:

So I meant using IApplicationEventHandler is the recommended way forward from now on.

Avatar for Anon Anon | December 6 2012 01:48
How about a zipped solution of the project shown above, for us newbies?

Avatar for Sebastiaan Janssen Sebastiaan Janssen | December 6 2012 10:11
@Anon I don't use this approach any more, but you should look at this one, it will have all you need:

Avatar for Sebastiaan Janssen Sebastiaan Janssen | December 6 2012 10:27
Hmm, commented on the wrong post =)

90% of this post is the basic Web API "hello world" project, it's not hard to follow along..

But here goes:

Make sure you have NuGet installed in Visual Studio and that package restore is allowed in the Package Manager settings.

Backoffice username: admin password: admin

Avatar for Anon Anon | December 10 2012 09:48
That's awesome, thanks a mil!

Avatar for Damian Damian | February 11 2013 11:33
Hi Sebastiaan

Do you know the best way to utilise WebAPI v Standard Controllers in Umbraco v6.

Been trying to get WEBApi to play nicely in a separate project for v6 like you have in this article and not having a great deal of luck at the moment.


Avatar for Sebastiaan Janssen Sebastiaan Janssen | February 11 2013 16:41
@Damian Register the route like so:

In web.config add ~/api in the umbracoReservedPaths and create an ApiController class like above (just start with the default example to test if it works and go to /api/values).

Avatar for Ameer Ameer | March 22 2013 09:25
Hi Sebastiaan
I'm using v6 , added the ~/api/ in the web.config, registered the route from and created the apiController but It still not working and I get: The resource cannot be found, HTTP 404.
do you see that I missed something?

Avatar for Damian Damian | February 12 2013 11:42
Aweome. I actually game back to say i managed to get it working using the AppStart example for the old version but saw your reply.

Gave it a whirl and it works great - and much cleaner! :)

Thanks Sebastiaan.

Avatar for Charles Zipp Charles Zipp | April 22 2013 00:10
For anyone that may have issues with this on V6...

I was not able to get this to work. I was getting a 404 when i would try to browse to my api url. The problem was that i was using IApplicationStartupHandler. This is referenced by the url above ( However, if you download sabastiaan's sample project, he is using IApplicationEventHandler. Once i switched to that, all worked fine.

May want to get that git doc updated...

Avatar for Charles Zipp Charles Zipp | April 22 2013 00:12
Just also wanted to thank Sabastiaan for taking the time to write up this article! Good read!