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.

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

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 .

Public APIs in Umbraco

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

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:

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

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

Examples

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

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

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

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

Backoffice API Controllers