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.
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 are similar to standard ASP.NET Core APIs. Below is an example of how to create an API in Umbraco:
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.
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.
In this example, any logged in member can access all actions in the ProductsController
controller:
This example allows only logged-in members of type "Retailers" to access the GetAll
action:
In this example, only members belonging to the "VIP" group can access any actions on the controller:
This example allows only members with IDs 1, 10, and 20
to access the GetAll
action:
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.
Tips to porting over API controllers from Umbraco 13 and below
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.
UmbracoApiController
implementationsUmbracoApiController
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:
...is routing-wise equivalent to this UmbracoApiController
implementation:
In both cases, the API endpoint will be available at /umbraco/api/products/getall
.
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:
...is routing wise equivalent to this [PluginController]
annotated implementation:
In both cases, the API endpoint will be available at /umbraco/shop/products/getall
.
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 for a comprehensive guide to writing APIs for the Management API.