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 Creating a Backoffice API article for a comprehensive guide to writing APIs for the Management API.
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.
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.
A public API in Umbraco is created as any other ASP.NET Core API:
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.
Read more about members and member login in the Member Registration and Login article.
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:
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.