Umbraco API Controllers

A guide to implementing APIs in Umbraco projects

This article describes how to work with API Controllers in Umbraco to create REST services.

In Umbraco 13 and below, the recommended approach was to base API controllers on the UmbracoApiController class. However, UmbracoApiController is obsolete in Umbraco 14 and will be removed in Umbraco 15.

Read the article Porting old Umbraco APIs for more details.

What is an API?

The Microsoft ASP.NET Core API documentation is a great place to familiarize yourself with API concepts. It can be found on the official ASP.NET Core site.

Public APIs in Umbraco

A public API in Umbraco is created as any other ASP.NET Core API:

ProductsController.cs

using Microsoft.AspNetCore.Mvc;

namespace UmbracoDocs.Samples;

[ApiController]
[Route("/api/shop/products")]
public class ProductsController : Controller
{
    [HttpGet]
    public IActionResult GetAll() => Ok(new[] { "Table", "Chair", "Desk", "Computer" });
}

Adding member protection to public APIs

To protect your APIs based on front-end membership, you can annotate your API controllers with the [UmbracoMemberAuthorize] attribute.

There are 3 parameters that can be supplied to control how the authorization works:

// Comma delimited list of allowed member types
string AllowType

// Comma delimited list of allowed member groups
string AllowGroup

// Comma delimited list of allowed member Ids
string AllowMembers

To allow all members, use the attribute without supplying any parameters.

You can apply these attributes either at controller level or at action level.

Read more about members and member login in the Member Registration and Login article.

Examples

This will allow any logged in member to access all actions in the ProductsController controller:

ProductsController.cs

using Microsoft.AspNetCore.Mvc;
using Umbraco.Cms.Web.Common.Filters;

namespace UmbracoDocs.Samples;

[ApiController]
[Route("/api/shop/products")]
[UmbracoMemberAuthorize]
public class ProductsController : Controller
{
    [HttpGet]
    public IActionResult GetAll() => Ok(new[] { "Table", "Chair", "Desk", "Computer" });
}

This will only allow logged in members of type "Retailers" to access the GetAll action:

ProductsController.cs

using Microsoft.AspNetCore.Mvc;
using Umbraco.Cms.Web.Common.Filters;

namespace UmbracoDocs.Samples;

[ApiController]
[Route("/api/shop/products")]
public class ProductsController : Controller
{
    [HttpGet]
    [UmbracoMemberAuthorize("Retailers", "", "")]
    public IActionResult GetAll() => Ok(new[] { "Table", "Chair", "Desk", "Computer" });
}

This will only allow members belonging to the "VIP" group to access any actions on the controller:

ProductsController.cs

using Microsoft.AspNetCore.Mvc;
using Umbraco.Cms.Web.Common.Filters;

namespace UmbracoDocs.Samples;

[ApiController]
[Route("/api/shop/products")]
[UmbracoMemberAuthorize("", "VIP", "")]
public class ProductsController : Controller
{
    [HttpGet]
    public IActionResult GetAll() => Ok(new[] { "Table", "Chair", "Desk", "Computer" });
}

This will only allow the members with ids 1, 10 and 20 to access the GetAll action:

ProductsController.cs

using Microsoft.AspNetCore.Mvc;
using Umbraco.Cms.Web.Common.Filters;

namespace UmbracoDocs.Samples;

[ApiController]
[Route("/api/shop/products")]
public class ProductsController : Controller
{
    [HttpGet]
    [UmbracoMemberAuthorize("", "", "1,10,20")]
    public IActionResult GetAll() => Ok(new[] { "Table", "Chair", "Desk", "Computer" });
}

Backoffice API Controllers

Read the Creating a Backoffice API article for a comprehensive guide to writing APIs for the Management API.

The Umbraco Backoffice API is also known as the Management API. Thus, a Backoffice API Controller is often referred to as a Management API Controller.