Umbraco API Controllers

A guide to implementing APIs in Umbraco projects

This article describes how to work with API controllers in Umbraco projects. It focuses on creating REST services using ASP.NET Core-based API controllers.

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.

API Overview

To better understand the basics of APIs, you can see the Microsoft ASP.NET Core API documentation. The documentation provides a solid foundation for API concepts in .NET environments..

Public APIs in Umbraco

Public APIs in Umbraco are similar to standard ASP.NET Core APIs. Below is an example of how to create an API in Umbraco:

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

You can secure your public APIs using front-end membership protection with the [UmbracoMemberAuthorize] attribute. This attribute allows you to restrict access based on member types, groups, or specific member IDs.

The available parameters are:

• AllowType: A comma-delimited list of allowed member types.

• AllowGroup: A comma-delimited list of allowed member groups.

• AllowMembers: A comma-delimited list of allowed member IDs.

To allow all members, apply the [UmbracoMemberAuthorize] attribute without parameters.

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

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

Examples of Member Protection

The [UmbracoMemberAuthorize] attribute offers flexible options for securing your public APIs in Umbraco. The following examples show different ways to apply member protection, such as how to restrict access by member type, group, or specific IDs.

Example 1: Allow All Logged-In Members

In this example, any logged in member can 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" });
}

Example 2: Restrict Access by Member Type

This example allows only 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" });
}

Example 3: Restrict Access by Member Group

In this example, only members belonging to the "VIP" group can 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" });
}

Example 4: Restrict Access by Member IDs

This example allows only 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

Umbraco's Backoffice API is also known as the Management API. When you create API controllers for Umbraco's backoffice, you are writing Management API controllers.

For a detailed guide on how to create APIs for the Backoffice, see the Creating a Backoffice API article article.