How To Create A Web Api In Umbraco In Less Than 5 Minutes!

Building an API within a project is a pretty standard process now. When you use .NET and MVC you can use web API to set-up an API layer pretty easily. In a standard .NET approach, you create a service that inherits from a controller, define some routes, update your route config to point to your controller and off you go. In a bog standard website this is usually all you need. When you work with any .NET CMS solution, however, you need to work with virtual page. Virtual pages creates two main issues, first, Umbraco needs to translate all the incoming requests to your virtual page URL’s to an MVC controller. In normal MVC URL’s normally point to the controller/action so there are some differences here that can contain a few hidden surprises. Second, when you work with page you need to use Umbraco API’s to do interesting stuff with that content. A normal web API controller won’t know anything about Umbraco, which will usually result in you having to create some custom solution to inject the things you need.

Lucky, Umbraco ships with a really useful controller, called the ‘UmbracoApiController’. Like the Surface controller, or, the RenderMvcController, the UmbracoApiController makes your life a little bit easier when you work with Umbraco by providing some Umbraco specific features. In today’s tutorial, I’m going to cover the basics that will get you up and running with a custom Umbraco Web API.

What is the different between a web API and the UmbracoApiController ?

I think it’s best to start off this by saying that if you want to create a Web API on your project, you can do everything you need using standard .NET MVC routing and a normal controller. If you need an API to talk to your non-Umbraco related data for example, then creating a standard .NET API will work just fine.

The reason why you might want to consider using the Umbraco controller then, is to make your life a little easier if you need to work with Umbraco object. Some of the main benefits of the Umbraco API include:

1. You won’t need to mess around with your Route Config. When you use the Umbraco version, you will automatically be able to access it using

2. Instead of having to inject any Umbraco dependencies you may need to use in your API. THe Umbraco Web API exposes several for you, including ApplicationContext, ServiceContex, DatabaseContext, UmbracoHelper, UmbracoContext UmbracoContext

Below shows a brief of example of a basic Umbraco Web API I created:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Web.Mvc;
using Umbraco.Web.WebApi;
namespace JonDJones.Core.Controllers.WebAPI
public class PostsApiController : UmbracoApiController
public string Test()
return "ws";

If you add this in to your project you can then access it using:

You might be surprised about how simple and easy the process is. You should be able to get up and running with Umbraco Web API literally within a few minutes, it really is that simple.

Troubleshooting Tips

If you are struggling to get Postman working, one nifty feature is being able to render out the URL via code. When I’ve worked with other CMS systems and plain old vanilla MVC, this snippet would have saved me a few hours:

var url = string.Format("{0}://{1}{2}", Request.Url.Scheme, Request.Url.Authority, Url.GetUmbracoApiService<PostsApiController>("Test"));
API URL = @url

If you add the above snippet into one of your Razors views, then Umbraco will render the URL to your API for you. This completely removes,

Jon D Jones

Software Architect, Programmer and Technologist Jon Jones is founder and CEO of London-based tech firm Digital Prompt. He has been working in the field for nearly a decade, specializing in new technologies and technical solution research in the web business. A passionate blogger by heart , speaker & consultant from England.. always on the hunt for the next challenge

More Posts

0 replies

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

Your email address will not be published. Required fields are marked *