1 of 7

Creating a backoffice API

In this article, you will learn how to create your own API in the Umbraco backoffice. This is a great way to extend the functionality of the Umbraco backoffice and create custom endpoints for your use.

The end result for this article is to create a custom API called "My item API" in the Management API found at /umbraco/swagger/.

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.

Creating the class

To create a custom API, you need to create a class that inherits from Umbraco.Cms.Web.BackOffice.Controllers.ManagementApiControllerBase.

The ManagementApiControllerBase serves as the foundation for your custom API class. It provides essential functionalities and utilities required for managing APIs within the Umbraco backoffice environment.

We also use the VersionedApiBackOfficeRoute attribute to define the route for our API. This attribute takes a string parameter that defines the route for the API. This route will be appended to the base route for the backoffice API.

MyItemApiController.cs

[VersionedApiBackOfficeRoute("my/item")]
[ApiExplorerSettings(GroupName = "My item API")]
public class MyItemApiController : ManagementApiControllerBase
{
}

Retrieving all items

Now that we have our class set up, we can add an action to get all items. We will use the HttpGet attribute to define the HTTP method and route for the action.

The AllItems field is an in-memory list of items to simulate the use of a repository. We use the skip & take parameters here, so users of this endpoint can implement paging. We also use the PagedViewModel to return the given items (10 by default), and then the total number of items.

MyItemApiController.cs

[HttpGet]
public IActionResult GetAllItems(int skip = 0, int take = 10)
    => Ok(
        new PagedViewModel<MyItem>
        {
            Items = AllItems.Skip(skip).Take(take),
            Total = AllItems.Count
        }
    );

AllItems is a local list:

MyItemApiController.cs

private static readonly List<MyItem> AllItems = Enumerable.Range(1, 100)
        .Select(i => new MyItem($"My Item #{i}"))
        .ToList();

The model for MyItem is a basic class with an Id and a Value property.

MyItem.cs

public class MyItem(string value)
{
    public Guid Id { get; } = Guid.NewGuid();

    public string Value { get; set; } = value;
}

Retrieving a single item

We can now create some logic to return a response based on the ID. The route parameter {id:guid} specifies that the id parameter should be a GUID. Here we're creating a local in-memory list of items and returning the item with the matching ID.

To note here is the use of the OperationStatusResult method. This method allows you to return a response with a status code and a body. This is useful for returning error responses with additional information.

The method also needs an enum operationStatus, as it will be attached to the response. This is a basic example, however, this OperationStatus would be returned from your service layer, based on the error in the service layer method.

MyItemApiController.cs

[HttpGet("{id:guid}")]
public IActionResult GetItem(Guid id)
{
    MyItem? item = AllItems.FirstOrDefault(item => item.Id == id);

    return item is not null
        ? Ok(item)
        : OperationStatusResult(
            MyItemOperationStatus.NotFound,
            builder => NotFound(
                builder
                    .WithTitle("That thing wasn't there")
                    .WithDetail("Maybe look for something else?")
                    .Build()
            )
        );
}

MyItemOperationStatus.cs

public enum MyItemOperationStatus
{
    NotFound,
    InvalidValue,
    DuplicateValue
}

Creating a new item

We can now add an action to create a new item. We use the HttpPost attribute to define the HTTP method and route for the action. Here we can see some validation logic.

If the value does not start with "New", we return a BadRequest response with an error message. This highlights why we use the OperationStatusResult method. We can return a detailed response.

We also use CreatedAtId<MyItemApiController>, a helper method to create a response with a 201 Created status code and a Location header.

MyItemApiController.cs

[HttpPost]
public IActionResult CreateItem(string value)
{
    if (value.StartsWith("New") is false)
    {
        return OperationStatusResult(
            MyItemOperationStatus.InvalidValue,
            builder => BadRequest(
                builder
                    .WithTitle("That was invalid")
                    .Build()
            )
        );
    }

    if (AllItems.Any(item => item.Value.InvariantEquals(value)))
    {
        return OperationStatusResult(
            MyItemOperationStatus.DuplicateValue,
            builder => BadRequest(
                builder
                    .WithTitle("No duplicate values, please.")
                    .Build()
            )
        );
    }

    var newItem = new MyItem(value);
    AllItems.Add(newItem);
    return CreatedAtId<MyItemApiController>(
        ctrl => nameof(ctrl.GetItem),
        newItem.Id
    );
}

Updating an item

Now we can add an action to update an item. We can use the HttpPut attribute to define the HTTP method and route for the action.

MyItemApiController.cs

[HttpPut("{id:guid}")]
public IActionResult UpdateItem(Guid id, string value)
{
    MyItem? item = AllItems.FirstOrDefault(item => item.Id == id);
    if (item is null)
    {
        return OperationStatusResult(
            MyItemOperationStatus.NotFound,
            builder => NotFound(
                builder
                    .WithTitle("That thing wasn't there")
                    .WithDetail("Maybe look for something else?")
                    .Build()
            )
        );
    }

    if (AllItems.Any(i => i.Value.InvariantEquals(value)))
    {
        return OperationStatusResult(
            MyItemOperationStatus.DuplicateValue,
            builder => BadRequest(
                builder
                    .WithTitle("You have been DUPED")
                    .Build()
            )
        );
    }

    item.Value = value;
    return Ok();
}

Deleting an item

Finally, we can add an action to delete an item. We can use the HttpDelete attribute to define the HTTP method and route for the action.

MyItemApiController.cs

[HttpDelete("{id:guid}")]
public IActionResult DeleteItem(Guid id)
{
    MyItem? item = AllItems.FirstOrDefault(item => item.Id == id);

    if (item is null)
    {
        return OperationStatusResult(
            MyItemOperationStatus.NotFound,
            builder => NotFound(
                builder
                    .WithTitle("That thing wasn't there")
                    .WithDetail("Maybe look for something else?")
                    .Build()
            )
        );
    }

    AllItems.Remove(item);
    return Ok();
}

Now we have created the custom API for our Umbraco project. Below you can see the full example of the implementation.

Full implementation

MyItemApiController.cs

using Microsoft.AspNetCore.Mvc;
using Umbraco.Cms.Api.Common.Attributes;
using Umbraco.Cms.Api.Common.ViewModels.Pagination;
using Umbraco.Cms.Api.Management.Controllers;
using Umbraco.Cms.Api.Management.Routing;

namespace UmbracoDocs.Samples;

[VersionedApiBackOfficeRoute("my/item")]
[ApiExplorerSettings(GroupName = "My item API")]
public class MyItemApiController : ManagementApiControllerBase
{
    private static readonly List<MyItem> AllItems = Enumerable.Range(1, 100)
        .Select(i => new MyItem($"My Item #{i}"))
        .ToList();

    [HttpGet]
    public IActionResult GetAllItems(int skip = 0, int take = 10)
        => Ok(
            new PagedViewModel<MyItem>
            {
                Items = AllItems.Skip(skip).Take(take),
                Total = AllItems.Count
            }
        );

    [HttpGet("{id:guid}")]
    public IActionResult GetItem(Guid id)
    {
        MyItem? item = AllItems.FirstOrDefault(item => item.Id == id);

        return item is not null
            ? Ok(item)
            : OperationStatusResult(
                MyItemOperationStatus.NotFound,
                builder => NotFound(
                    builder
                        .WithTitle("That thing wasn't there")
                        .WithDetail("Maybe look for something else?")
                        .Build()
                )
            );
    }

    [HttpPost]
    public IActionResult CreateItem(string value)
    {
        if (value.StartsWith("New") is false)
        {
            return OperationStatusResult(
                MyItemOperationStatus.InvalidValue,
                builder => BadRequest(
                    builder
                        .WithTitle("That was invalid")
                        .Build()
                )
            );
        }

        if (AllItems.Any(item => item.Value.InvariantEquals(value)))
        {
            return OperationStatusResult(
                MyItemOperationStatus.DuplicateValue,
                builder => BadRequest(
                    builder
                        .WithTitle("No duplicate values, please.")
                        .Build()
                )
            );
        }

        var newItem = new MyItem(value);
        AllItems.Add(newItem);
        return CreatedAtId<MyItemApiController>(
            ctrl => nameof(ctrl.GetItem),
            newItem.Id
        );
    }

    [HttpPut("{id:guid}")]
    public IActionResult UpdateItem(Guid id, string value)
    {
        MyItem? item = AllItems.FirstOrDefault(item => item.Id == id);
        if (item is null)
        {
            return OperationStatusResult(
                MyItemOperationStatus.NotFound,
                builder => NotFound(
                    builder
                        .WithTitle("That thing wasn't there")
                        .WithDetail("Maybe look for something else?")
                        .Build()
                )
            );
        }

        if (AllItems.Any(i => i.Value.InvariantEquals(value)))
        {
            return OperationStatusResult(
                MyItemOperationStatus.DuplicateValue,
                builder => BadRequest(
                    builder
                        .WithTitle("You have been DUPED")
                        .Build()
                )
            );
        }

        item.Value = value;
        return Ok();
    }

    [HttpDelete("{id:guid}")]
    public IActionResult DeleteItem(Guid id)
    {
        MyItem? item = AllItems.FirstOrDefault(item => item.Id == id);

        if (item is null)
        {
            return OperationStatusResult(
                MyItemOperationStatus.NotFound,
                builder => NotFound(
                    builder
                        .WithTitle("That thing wasn't there")
                        .WithDetail("Maybe look for something else?")
                        .Build()
                )
            );
        }

        AllItems.Remove(item);
        return Ok();
    }
}

public class MyItem(string value)
{
    public Guid Id { get; } = Guid.NewGuid();

    public string Value { get; set; } = value;
}

public enum MyItemOperationStatus
{
    NotFound,
    InvalidValue,
    DuplicateValue
}

Documenting your controllers

Documenting your API controllers using Swagger in Umbraco Version 14 simplifies the creation of detailed and interactive API documentation. Adding Swagger attributes automatically generates comprehensive information about routes, parameters, and response types. This will enhance the developer experience and ensure clarity and consistency in your API documentation.

ApiExplorerSettings

With the ApiExplorerSettings attribute, we can put all our endpoints into a given group. This is a nice way of organizing our endpoints in the Swagger UI.

MyItemApiController.cs

[ApiExplorerSettings(GroupName = "My item API")]
public class MyItemApiController : ManagementApiControllerBase

ProducesResponseType Attribute

Use [ProducesResponseType] to specify the possible responses for each action method. This helps Swagger generate accurate documentation for your API. For example, in the GetItem method:

MyItemApiController.cs

[HttpGet("{id:guid}")]
[ProducesResponseType<MyItem>(StatusCodes.Status200OK)]
[ProducesResponseType<ProblemDetails>(StatusCodes.Status404NotFound)]
public IActionResult GetItem(Guid id)
{
// Method implementation
}

Here, [ProducesResponseType] specifies that a 200 OK response will return a MyItem, and a 404 Not Found response will return a ProblemDetails.

Example Documentation for Each Controller Method

To get an idea of how to document each controller method, below are some examples of how to document each operation for an API controller. The controller is from the Creating your own API article

GetAllItems

MyItemApiController.cs

[HttpGet]
[ProducesResponseType<PagedViewModel<MyItem>>(StatusCodes.Status200OK)]
public IActionResult GetAllItems(int skip = 0, int take = 10)

GetItem

MyItemApiController.cs

[HttpGet("{id:guid}")]
[ProducesResponseType<MyItem>(StatusCodes.Status200OK)]
[ProducesResponseType<ProblemDetails>(StatusCodes.Status404NotFound)]
public IActionResult GetItem(Guid id)

CreateItem

MyItemApiController.cs

[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType<ProblemDetails>(StatusCodes.Status400BadRequest)]
public IActionResult CreateItem(string value)

UpdateItem

MyItemApiController.cs

[HttpPut("{id:guid}")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType<ProblemDetails>(StatusCodes.Status400BadRequest)]
[ProducesResponseType<ProblemDetails>(StatusCodes.Status404NotFound)]
public IActionResult UpdateItem(Guid id, string value)

DeleteItem

MyItemApiController.cs

[HttpDelete("{id:guid}")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType<ProblemDetails>(StatusCodes.Status404NotFound)]
public IActionResult DeleteItem(Guid id)

Verifying the changes

Run your application and navigate to the Swagger UI (typically found at /swagger). Verify that your API documentation is correctly displaying the routes, parameters, and response types.

Adding a custom Swagger document

Adding a custom Swagger document for a custom Management API

By default, all controllers based on ManagementApiControllerBase will be included in the default Management API Swagger document.

When building custom Management API controllers, sometimes it's preferable to have a dedicated Swagger document for them. Doing so is a three-step process:

Register the Swagger document with Swagger UI.
Instruct Swagger UI to utilize Umbraco authentication for the Swagger document.
Move the controllers to the Swagger document.

The following code exemplifies how to achieve the first two steps;

With this in place, the last step is to annotate the relevant API controllers with the MapToApi attribute:

Now when we visit the Swagger UI, "My item API" has its own Swagger document:

Versioning your API

Adding new versions of custom Management APIs

All APIs register as version 1.0 by default, which means their endpoints are routed under /umbraco/management/api/v1/.

As projects evolve, adding new versions of your APIs sometimes becomes necessary. Multiple versions of the same API can co-exist to retain backward compatibility.

APIs are versioned using attribute annotation:

[ApiVersion] attributes on the API controllers.
[MapToApiVersion] attributes on the API controller actions.

It is recommended to annotate all API controller actions, as well as the version 1.0 actions.

Using the API controller from the Creating your own API article as an example, we can add version 2.0 implementations of select actions:

MyItemApiController.cs

[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class MyItemApiController : ManagementApiControllerBase
{
    [HttpGet]
    [MapToApiVersion("1.0")]
    public IActionResult GetAllItems(int skip = 0, int take = 10)
    {
        // ...
    }

    [HttpGet("{id:guid}")]
    [MapToApiVersion("1.0")]
    public IActionResult GetItem(Guid id)
    {
        // ...
    }

    [HttpPost]
    [MapToApiVersion("1.0")]
    public IActionResult CreateItem(string value)
    {
        // ...
    }

    [HttpPut("{id:guid}")]
    [MapToApiVersion("1.0")]
    public IActionResult UpdateItem(Guid id, string value)
    {
        // ...
    }

    [HttpDelete("{id:guid}")]
    [MapToApiVersion("1.0")]
    public IActionResult DeleteItem(Guid id)
    {
        // ...
    }

    [HttpGet("{id:guid}")]
    [MapToApiVersion("2.0")]
    public IActionResult GetItemV2(Guid id)
    {
        MyItem? item = AllItems.FirstOrDefault(item => item.Id == id);

        return item is not null
            ? Ok(item)
            : OperationStatusResult(
                MyItemOperationStatus.NotFound,
                builder => NotFound(
                    builder
                        .WithTitle("The item was not found")
                        .WithDetail("The item with the given ID did not exist.")
                        .Build()
                )
            );
    }

    [HttpPost]
    [MapToApiVersion("2.0")]
    public IActionResult CreateItemV2(string value)
    {
        var newItem = new MyItem(value);
        AllItems.Add(newItem);
        return CreatedAtId<MyItemApiController>(
            ctrl => nameof(ctrl.GetItemV2),
            newItem.Id
        );
    }
}

Version 2.0 of the "get" and "create" endpoints - GetItemV2 and CreateItemV2 respectively, are added with the code above. The rest of the endpoints remain version 1.0 only.

The version 2.0 endpoints are routed under /umbraco/management/api/v2/.

In the example above, the version 2.0 actions are added to the same API controller as their version 1.0 counterparts. If you prefer, they can be added to a new API controller instead. This will leave you with separate API controllers, one for each version of the API. See the examples below:

MyItemApiController.cs

[ApiVersion("1.0")]
public class MyItemApiController : ManagementApiControllerBase
{
    [HttpGet]
    [MapToApiVersion("1.0")]
    public IActionResult GetAllItems(int skip = 0, int take = 10)
    {
        // ...
    }

    [HttpGet("{id:guid}")]
    [MapToApiVersion("1.0")]
    public IActionResult GetItem(Guid id)
    {
        // ...
    }

    [HttpPost]
    [MapToApiVersion("1.0")]
    public IActionResult CreateItem(string value)
    {
        // ...
    }

    [HttpPut("{id:guid}")]
    [MapToApiVersion("1.0")]
    public IActionResult UpdateItem(Guid id, string value)
    {
        // ...
    }

    [HttpDelete("{id:guid}")]
    [MapToApiVersion("1.0")]
    public IActionResult DeleteItem(Guid id)
    {
        // ...
    }
}

With the version 1.0 actions added in a controller sampled above, the version 2.0 actions are added in a new controller, as shown below.

MyItemApiVersionTwoController.cs

[ApiVersion("2.0")]
public class MyItemApiVersionTwoController : ManagementApiControllerBase
{
    private static readonly List<MyItem> AllItems = Enumerable.Range(1, 100)
        .Select(i => new MyItem($"My V2 Item #{i}"))
        .ToList();

    [HttpGet("{id:guid}")]
    [MapToApiVersion("2.0")]
    public IActionResult GetItem(Guid id)
    {
        MyItem? item = AllItems.FirstOrDefault(item => item.Id == id);

        return item is not null
            ? Ok(item)
            : OperationStatusResult(
                MyItemOperationStatus.NotFound,
                builder => NotFound(
                    builder
                        .WithTitle("The item was not found")
                        .WithDetail("The item with the given ID did not exist.")
                        .Build()
                )
            );
    }

    [HttpPost]
    [MapToApiVersion("2.0")]
    public IActionResult CreateItem(string value)
    {
        var newItem = new MyItem(value);
        AllItems.Add(newItem);
        return CreatedAtId<MyItemApiVersionTwoController>(
            ctrl => nameof(ctrl.GetItem),
            newItem.Id
        );
    }
}

While perhaps tempting, do not name your API controller V2 - e.g. MyItemApiVersionV2. Due to an upstream issue in the API versioning system, this will currently cause routing issues in certain scenarios.

Polymorphic output in the Management API

How to support polymorphic outputs from custom Management APIs

For security reasons, the System.Text.Json serializer will not serialize types that are not explicitly referenced at compile time.

This can be a challenge when dealing with polymorphic API outputs. As a workaround, the Management API provides two options for enabling polymorphic outputs.

Polymorphism by interface

This approach requires that all output models implement the same interface - for example:

IMyItem.cs

public interface IMyItem
{
    Guid Id { get; }

    string Value { get; set; }
}

MyItem.cs

public class MyItem(string value) : IMyItem
{
    public Guid Id { get; } = Guid.NewGuid();

    public string Value { get; set; } = value;
}

MyOtherItem.cs

public class MyOtherItem(string value, int otherValue) : IMyItem
{
    public Guid Id { get; } = Guid.NewGuid();

    public string Value { get; set; } = value;

    public int OtherValue { get; } = otherValue;
}

The ProducesResponseType annotation on the endpoints must also be updated to use the interface:

MyItemApiController.cs

...
[ProducesResponseType<PagedViewModel<IMyItem>>(StatusCodes.Status200OK)]
public IActionResult GetAllItems(int skip = 0, int take = 10)
...
[ProducesResponseType<IMyItem>(StatusCodes.Status200OK)]
public IActionResult GetItem(Guid id)
...

Polymorphism by annotation

This approach requires that all output models implement a common base class. The base class will define all its derived types by annotation - for example:

MyItemBase.cs

[JsonDerivedType(typeof(MyItem), nameof(MyItem))]
[JsonDerivedType(typeof(MyOtherItem), nameof(MyOtherItem))]
public abstract class MyItemBase(string value)
{
    public Guid Id { get; } = Guid.NewGuid();

    public string Value { get; set; } = value;
}

MyItem.cs

public class MyItem(string value) : MyItemBase(value)
{
}

MyOtherItem.cs

public class MyOtherItem(string value, int otherValue) : MyItemBase(value)
{
    public int OtherValue { get; } = otherValue;
}

The ProducesResponseType annotation on the endpoints must also be updated to use the base class:

MyItemApiController.cs

...
[ProducesResponseType<PagedViewModel<MyItemBase>>(StatusCodes.Status200OK)]
public IActionResult GetAllItems(int skip = 0, int take = 10)
...
[ProducesResponseType<MyItemBase>(StatusCodes.Status200OK)]
public IActionResult GetItem(Guid id)
...

Umbraco schema and operation IDs

How to apply the Umbraco schema and operation IDs for custom Management APIs

All core Management APIs have a custom scheme for their generated OpenAPI schema and operation IDs.

This scheme is strictly opt-in to avoid affecting custom APIs by default. In this article, we'll see how to opt-in to the scheme.

If you are happy with your APIs' default schema and operation IDs, nothing is likely gained by using the Umbraco ones.

Schema IDs

Schema IDs are handled by ISchemaIdHandler implementations. To opt-in to the Umbraco schema IDs, we base our implementation on the core handler:

SampleSchemaIdHandler.cs

using Umbraco.Cms.Api.Common.OpenApi;

namespace UmbracoDocs.Samples;

// this schema ID handler extends the Umbraco schema IDs
// to all types in the UmbracoDocs.Samples namespace
public class SampleSchemaIdHandler : SchemaIdHandler
{
    public override bool CanHandle(Type type)
        => type.Namespace == "UmbracoDocs.Samples";
}

Then, we implement a composer to register the new schema ID handler:

SampleSchemaIdComposer.cs

using Umbraco.Cms.Api.Common.OpenApi;
using Umbraco.Cms.Core.Composing;

namespace UmbracoDocs.Samples;

public class SampleSchemaIdComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
        =>  builder.Services.AddSingleton<ISchemaIdHandler, SampleSchemaIdHandler>();
}

Operation IDs

Operation IDs follow the same pattern as schema IDs. The only difference is that the IOperationIdHandler operates at the API level, not at the type level.

Again, to opt-in to the Umbraco operation IDs, we base our implementation on the core handler:

SampleOperationIdHandler.cs

using Asp.Versioning;
using Microsoft.AspNetCore.Mvc.ApiExplorer;
using Microsoft.AspNetCore.Mvc.Controllers;
using Microsoft.Extensions.Options;
using Umbraco.Cms.Api.Common.OpenApi;

namespace UmbracoDocs.Samples;

// this operation ID handler extends the Umbraco operation IDs
// to all API controllers in the UmbracoDocs.Samples namespace
public class SampleOperationIdHandler : OperationIdHandler
{
    public SampleOperationIdHandler(IOptions<ApiVersioningOptions> apiVersioningOptions)
        : base(apiVersioningOptions)
    {
    }

    protected override bool CanHandle(ApiDescription apiDescription, ControllerActionDescriptor controllerActionDescriptor)
        => controllerActionDescriptor.ControllerTypeInfo.Namespace == "UmbracoDocs.Samples";
}

Then, we implement a composer to register the new operation ID handler:

SampleOperationIdComposer.cs

using Umbraco.Cms.Api.Common.OpenApi;
using Umbraco.Cms.Core.Composing;

namespace UmbracoDocs.Samples;

public class SampleOperationIdComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
        =>  builder.Services.AddSingleton<IOperationIdHandler, SampleOperationIdHandler>();
}

Access policies

How to apply access policies for Management APIs

A Management API is by default available to any authorized Umbraco backoffice user.

To further restrict access we can apply access policies using the [Authorize] attribute.

Built-in access policies

Umbraco maintains a set of built-in access policies we can leverage in our own APIs. The policy names are defined in Umbraco.Cms.Web.Common.Authorization.AuthorizationPolicies.

For example, the following makes the API accessible only to users with Content section access:

MyItemApiController.cs

using Umbraco.Cms.Web.Common.Authorization;
...

[Authorize(AuthorizationPolicies.SectionAccessContent)]
public class MyItemApiController : ManagementApiControllerBase

Custom access policies

We can also define our own access policies. Custom access policies are a great way of keeping access control in sync across multiple endpoints, as projects evolve over time.

A custom access policy is defined by means of composition.

The following access policy definition requires the user to be a member of both the Umbraco Administrators group and a custom defined group:

SampleCustomPolicyComposer.cs

public class SampleCustomPolicyComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
        => builder.Services.AddAuthorization(options =>
            options.AddPolicy(SiteConstants.CustomPolicyName, policy =>
            {
                policy.AuthenticationSchemes.Add(OpenIddictValidationAspNetCoreDefaults.AuthenticationScheme);
                policy.RequireRole(SiteConstants.CustomGroupAlias);
                policy.RequireRole(Constants.Security.AdminGroupAlias);
            })
        );
}

SiteConstants.cs

public static class SiteConstants
{
    public const string CustomPolicyName = "Site.CustomPolicy";

    public const string CustomGroupAlias = "customGroup";
}

With the policy defined, we can apply it to the API controller:

MyItemApiController.cs

[Authorize(SiteConstants.CustomPolicyName)]
public class MyItemApiController : ManagementApiControllerBase

Creating a backoffice API

The end result for this article is to create a custom API called "My item API" in the Management API found at /umbraco/swagger/.

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.

Creating the class

To create a custom API, you need to create a class that inherits from Umbraco.Cms.Web.BackOffice.Controllers.ManagementApiControllerBase.

MyItemApiController.cs

[VersionedApiBackOfficeRoute("my/item")]
[ApiExplorerSettings(GroupName = "My item API")]
public class MyItemApiController : ManagementApiControllerBase
{
}

Retrieving all items

Now that we have our class set up, we can add an action to get all items. We will use the HttpGet attribute to define the HTTP method and route for the action.

MyItemApiController.cs

[HttpGet]
public IActionResult GetAllItems(int skip = 0, int take = 10)
    => Ok(
        new PagedViewModel<MyItem>
        {
            Items = AllItems.Skip(skip).Take(take),
            Total = AllItems.Count
        }
    );

AllItems is a local list:

MyItemApiController.cs

private static readonly List<MyItem> AllItems = Enumerable.Range(1, 100)
        .Select(i => new MyItem($"My Item #{i}"))
        .ToList();

The model for MyItem is a basic class with an Id and a Value property.

MyItem.cs

public class MyItem(string value)
{
    public Guid Id { get; } = Guid.NewGuid();

    public string Value { get; set; } = value;
}

Retrieving a single item

MyItemApiController.cs

[HttpGet("{id:guid}")]
public IActionResult GetItem(Guid id)
{
    MyItem? item = AllItems.FirstOrDefault(item => item.Id == id);

    return item is not null
        ? Ok(item)
        : OperationStatusResult(
            MyItemOperationStatus.NotFound,
            builder => NotFound(
                builder
                    .WithTitle("That thing wasn't there")
                    .WithDetail("Maybe look for something else?")
                    .Build()
            )
        );
}

MyItemOperationStatus.cs

public enum MyItemOperationStatus
{
    NotFound,
    InvalidValue,
    DuplicateValue
}

Creating a new item

We can now add an action to create a new item. We use the HttpPost attribute to define the HTTP method and route for the action. Here we can see some validation logic.

If the value does not start with "New", we return a BadRequest response with an error message. This highlights why we use the OperationStatusResult method. We can return a detailed response.

We also use CreatedAtId<MyItemApiController>, a helper method to create a response with a 201 Created status code and a Location header.

MyItemApiController.cs

[HttpPost]
public IActionResult CreateItem(string value)
{
    if (value.StartsWith("New") is false)
    {
        return OperationStatusResult(
            MyItemOperationStatus.InvalidValue,
            builder => BadRequest(
                builder
                    .WithTitle("That was invalid")
                    .Build()
            )
        );
    }

    if (AllItems.Any(item => item.Value.InvariantEquals(value)))
    {
        return OperationStatusResult(
            MyItemOperationStatus.DuplicateValue,
            builder => BadRequest(
                builder
                    .WithTitle("No duplicate values, please.")
                    .Build()
            )
        );
    }

    var newItem = new MyItem(value);
    AllItems.Add(newItem);
    return CreatedAtId<MyItemApiController>(
        ctrl => nameof(ctrl.GetItem),
        newItem.Id
    );
}

Updating an item

Now we can add an action to update an item. We can use the HttpPut attribute to define the HTTP method and route for the action.

MyItemApiController.cs

[HttpPut("{id:guid}")]
public IActionResult UpdateItem(Guid id, string value)
{
    MyItem? item = AllItems.FirstOrDefault(item => item.Id == id);
    if (item is null)
    {
        return OperationStatusResult(
            MyItemOperationStatus.NotFound,
            builder => NotFound(
                builder
                    .WithTitle("That thing wasn't there")
                    .WithDetail("Maybe look for something else?")
                    .Build()
            )
        );
    }

    if (AllItems.Any(i => i.Value.InvariantEquals(value)))
    {
        return OperationStatusResult(
            MyItemOperationStatus.DuplicateValue,
            builder => BadRequest(
                builder
                    .WithTitle("You have been DUPED")
                    .Build()
            )
        );
    }

    item.Value = value;
    return Ok();
}

Deleting an item

Finally, we can add an action to delete an item. We can use the HttpDelete attribute to define the HTTP method and route for the action.

MyItemApiController.cs

[HttpDelete("{id:guid}")]
public IActionResult DeleteItem(Guid id)
{
    MyItem? item = AllItems.FirstOrDefault(item => item.Id == id);

    if (item is null)
    {
        return OperationStatusResult(
            MyItemOperationStatus.NotFound,
            builder => NotFound(
                builder
                    .WithTitle("That thing wasn't there")
                    .WithDetail("Maybe look for something else?")
                    .Build()
            )
        );
    }

    AllItems.Remove(item);
    return Ok();
}

Now we have created the custom API for our Umbraco project. Below you can see the full example of the implementation.

Full implementation

MyItemApiController.cs

using Microsoft.AspNetCore.Mvc;
using Umbraco.Cms.Api.Common.Attributes;
using Umbraco.Cms.Api.Common.ViewModels.Pagination;
using Umbraco.Cms.Api.Management.Controllers;
using Umbraco.Cms.Api.Management.Routing;

namespace UmbracoDocs.Samples;

[VersionedApiBackOfficeRoute("my/item")]
[ApiExplorerSettings(GroupName = "My item API")]
public class MyItemApiController : ManagementApiControllerBase
{
    private static readonly List<MyItem> AllItems = Enumerable.Range(1, 100)
        .Select(i => new MyItem($"My Item #{i}"))
        .ToList();

    [HttpGet]
    public IActionResult GetAllItems(int skip = 0, int take = 10)
        => Ok(
            new PagedViewModel<MyItem>
            {
                Items = AllItems.Skip(skip).Take(take),
                Total = AllItems.Count
            }
        );

    [HttpGet("{id:guid}")]
    public IActionResult GetItem(Guid id)
    {
        MyItem? item = AllItems.FirstOrDefault(item => item.Id == id);

        return item is not null
            ? Ok(item)
            : OperationStatusResult(
                MyItemOperationStatus.NotFound,
                builder => NotFound(
                    builder
                        .WithTitle("That thing wasn't there")
                        .WithDetail("Maybe look for something else?")
                        .Build()
                )
            );
    }

    [HttpPost]
    public IActionResult CreateItem(string value)
    {
        if (value.StartsWith("New") is false)
        {
            return OperationStatusResult(
                MyItemOperationStatus.InvalidValue,
                builder => BadRequest(
                    builder
                        .WithTitle("That was invalid")
                        .Build()
                )
            );
        }

        if (AllItems.Any(item => item.Value.InvariantEquals(value)))
        {
            return OperationStatusResult(
                MyItemOperationStatus.DuplicateValue,
                builder => BadRequest(
                    builder
                        .WithTitle("No duplicate values, please.")
                        .Build()
                )
            );
        }

        var newItem = new MyItem(value);
        AllItems.Add(newItem);
        return CreatedAtId<MyItemApiController>(
            ctrl => nameof(ctrl.GetItem),
            newItem.Id
        );
    }

    [HttpPut("{id:guid}")]
    public IActionResult UpdateItem(Guid id, string value)
    {
        MyItem? item = AllItems.FirstOrDefault(item => item.Id == id);
        if (item is null)
        {
            return OperationStatusResult(
                MyItemOperationStatus.NotFound,
                builder => NotFound(
                    builder
                        .WithTitle("That thing wasn't there")
                        .WithDetail("Maybe look for something else?")
                        .Build()
                )
            );
        }

        if (AllItems.Any(i => i.Value.InvariantEquals(value)))
        {
            return OperationStatusResult(
                MyItemOperationStatus.DuplicateValue,
                builder => BadRequest(
                    builder
                        .WithTitle("You have been DUPED")
                        .Build()
                )
            );
        }

        item.Value = value;
        return Ok();
    }

    [HttpDelete("{id:guid}")]
    public IActionResult DeleteItem(Guid id)
    {
        MyItem? item = AllItems.FirstOrDefault(item => item.Id == id);

        if (item is null)
        {
            return OperationStatusResult(
                MyItemOperationStatus.NotFound,
                builder => NotFound(
                    builder
                        .WithTitle("That thing wasn't there")
                        .WithDetail("Maybe look for something else?")
                        .Build()
                )
            );
        }

        AllItems.Remove(item);
        return Ok();
    }
}

public class MyItem(string value)
{
    public Guid Id { get; } = Guid.NewGuid();

    public string Value { get; set; } = value;
}

public enum MyItemOperationStatus
{
    NotFound,
    InvalidValue,
    DuplicateValue
}