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 create 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 the 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 www.website.com/umbraco/api/controllername.

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

Below shows ane example code snippet for a basic Umbraco Web API controller:

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

http://www.website.com/umbraco/api/PostsApi/Test

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:

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