In this tutorial, you will learn how to build an API within a Umbraco CMS powered website. Building a .NET API is a pretty standard process now. You can use web API to get up and running with an API layer pretty easily. When creating an API in Umbraco there are a few nuances. In a vanilla .NET project, you create a controller that inherits from a special base class, you define an action and some business logic, and potentially update your route.config to point to your controller and off you go. When you work within a .NET CMS project the routing rules are different. The solution needs to work with virtual pages. The site URL structure can not simply map to a controller and an action like a normal .NET website. Virtual pages create two main issues. First, Umbracos handlers translate all the incoming requests to try to map the request to a virtual page. This means normal routing does not work the same in Umbraco as it does in a normal website. Second, when you create an API within a CMS you usually need to use the Umbraco API's to do interesting stuff. A normal web API controller won't know anything about Umbraco, which will usually result in you having to create a custom solution in order to get access to the APIs that you need. Lucky, Umbraco ships with a really useful controller, called the UmbracoApiController that makes creating APIs in Umbraco super-simple. If you want to create a Web API in your Umbraco project, you can create one using the standard .NET MVC functionality. The price is a little more set-up work. Seeing we like clean code and minimal work, I recommend creating an API the Umbraco way 😌!

Like, SurfaceController or RenderMvcController, the UmbracoApiController makes your life a little bit easier when you work with Umbraco. UmbracoApiControllerprovides some Umbraco specific features that will make API development a dream, sound good, then read on! The main benefits of using UmbracoApiController to build a Umbraco API include:

  1. You won't need to mess around with your route.config. When you use the Umbraco version, the routing will automatically work. All Umbraco APIs follow this structure ``www.website.com/umbraco/api/controllername`. Create a controller and you should be able to hit it easily!

  2. Instead of having to inject any Umbraco dependencies you may need to use in your controller. The Umbraco Web API exposes several base properties. This includes access to ApplicationContext, ServiceContext, DatabaseContext, UmbracoHelper, and UmbracoContext.

BY now I'm hoping I have convinced you to build your APIs using this specific base class. Let us now look at some code! Below shows the bare-bone code required to create a Umbraco Web API controller:

The URL to access this API would be

You might be surprised by 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 this simple. When creating an API it is a good idea to use Postman to test it works. If you are struggling to get Postman working, one nifty feature is being able to render out the URL via code to double-check you are calling the correct end-point. Adding this code can save you hours worth of debugging time!

Simply, add the above snippet into one of your Razors views, and let Umbraco render the URL to your API for you. Happy Coding 🤘