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.

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:

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.

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:

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:

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:

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:

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.

Umbraco 14 has obsoleted or removed base classes that were widely adopted for building APIs in previous versions of Umbraco. This article outlines the recommended approach for porting over APIs that were created before Umbraco 14.

Porting over UmbracoApiController implementations

UmbracoApiController is obsolete from Umbraco 14 and will be removed in Umbraco 15. The recommended approach is to base APIs on the ASP.NET Core Controller class instead.

UmbracoApiController would automatically route the API actions to /umbraco/api/[ControllerName]/[ControllerAction]. Moving forward, you control your API routes with the [Route] annotation.

If you rely on the route previously generated by UmbracoApiController, you can still create identical routes. For example, the following Controller implementation:

using Microsoft.AspNetCore.Mvc;

namespace UmbracoDocs.Samples;

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

...is routing-wise equivalent to this UmbracoApiController implementation:

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

namespace UmbracoDocs.Samples;

public class ProductsController : UmbracoApiController
{
    public IActionResult GetAll() => Ok(new[] { "Table", "Chair", "Desk", "Computer" });
}

In both cases, the API endpoint will be available at /umbraco/api/products/getall.

Porting over "plugin based" implementations

In previous versions of Umbraco, it was possible to route controllers to dedicated areas by annotating UmbracoApiController implementations with [PluginController]. This annotation would automatically route the API actions to /Umbraco/[PluginAreaName]/[ControllerName]/[ActionName].

As this approach was based on UmbracoApiController, it is no longer viable - use the [Route] annotation instead. For example, the following Controller implementation:

using Microsoft.AspNetCore.Mvc;

namespace UmbracoDocs.Samples;

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

...is routing wise equivalent to this [PluginController] annotated implementation:

using Microsoft.AspNetCore.Mvc;
using Umbraco.Cms.Web.Common.Attributes;
using Umbraco.Cms.Web.Common.Controllers;

namespace UmbracoDocs.Samples;

[PluginController("shop")]
public class ProductsController : UmbracoApiController
{
    public IActionResult GetAll() => Ok(new[] { "Table", "Chair", "Desk", "Computer" });
}

In both cases, the API endpoint will be available at /umbraco/shop/products/getall.

Backoffice API Controllers

The UmbracoAuthorizedApiController and UmbracoAuthorizedJsonController base classes have been removed in Umbraco 14. Moving forward, backoffice APIs (also known as Management APIs) must be based on the ManagementApiControllerBase.

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