Custom Delivery API endpoints

Implementing custom Delivery API endpoints.

Sometimes it can be useful to extend the Delivery API with custom endpoints.

At its core, a custom Delivery API endpoint is no different from an ordinary an API controller. However, there are a few tricks that can make your own endpoints feel more like part of the native Delivery API. These include:

• Consistent JSON serialization.

• Matching routing schemes.

• Swagger documentation.

• Authentication.

• Respecting the configured Delivery API access rules.

In this article you'll find snippets and examples to get you started.

A basic Delivery API endpoint

Here is a basic example of a Delivery API endpoint:

BasicDeliveryApiController.cs

using Asp.Versioning;
using Microsoft.AspNetCore.Mvc;
using Umbraco.Cms.Api.Delivery.Controllers;
using Umbraco.Cms.Api.Delivery.Filters;
using Umbraco.Cms.Api.Delivery.Routing;

namespace Umbraco.Docs;

[ApiVersion("2.0")]
[VersionedDeliveryApiRoute("custom")]
[ApiExplorerSettings(GroupName = "Custom")]
[DeliveryApiAccess]
public class BasicDeliveryApiController : DeliveryApiControllerBase
{
    [HttpGet("basic-api")]
    [MapToApiVersion("2.0")]
    [ProducesResponseType(typeof(int), StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
    [ProducesResponseType(StatusCodes.Status403Forbidden)]
    public IActionResult Get() => Ok(123);
}

Since a lot is happening above, you can explore the following sections to understand the implementations and attributes.

Implementing the DeliveryApiControllerBase ensures that:

• The endpoint is automatically included in the Swagger documentation for the Delivery API.

• The endpoint respects the JSON serialization scheme for the entire Delivery API.

There are also a few attributes applied to the endpoint:

• The ApiVersion and MapToApiVersion attributes match the endpoint version to the current Delivery API version.

• The VersionedDeliveryApiRoute attribute ensures that the endpoint routing matches that of the Delivery API.

• The ApiExplorerSettings attribute adds the endpoint to a custom group in the Swagger documentation.

• The DeliveryApiAccess attribute ensures that this endpoint can only be invoked if the Content Delivery API is enabled.

• The ProducesResponseType attributes help the Swagger documentation understand the endpoint.

DeliveryApiAccess also comes in a specific version for the Media Delivery API - the DeliveryApiMediaAccess attribute.

A Delivery API endpoint for content

If your custom Delivery API endpoint outputs content, you will likely find ContentApiControllerBase a better fit as a base class. Here is an example of how to use it:

ContentDeliveryApiController.cs

using Asp.Versioning;
using Microsoft.AspNetCore.Mvc;
using Umbraco.Cms.Api.Delivery.Controllers.Content;
using Umbraco.Cms.Api.Delivery.Routing;
using Umbraco.Cms.Core.DeliveryApi;
using Umbraco.Cms.Core.Models.DeliveryApi;

namespace Umbraco.Docs;

[ApiVersion("2.0")]
[VersionedDeliveryApiRoute("custom")]
[ApiExplorerSettings(GroupName = "Custom")]
public class ContentDeliveryApiController : ContentApiControllerBase
{
    public ContentDeliveryApiController(
        IApiPublishedContentCache apiPublishedContentCache,
        IApiContentResponseBuilder apiContentResponseBuilder)
        : base(apiPublishedContentCache, apiContentResponseBuilder)
    {
    }

    [HttpGet("content-api/{id:guid}")]
    [MapToApiVersion("2.0")]
    [ProducesResponseType(typeof(IApiContentResponse), StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
    [ProducesResponseType(StatusCodes.Status403Forbidden)]
    public async Task<IActionResult> Get(Guid id)
    {
        var content = await ApiPublishedContentCache.GetByIdAsync(id);
        return content is not null
            ? Ok(ApiContentResponseBuilder.Build(content))
            : NotFound();
    }
}

This endpoint does not require the DeliveryApiAccess attribute, because it is already defined on the base class.

The ContentApiControllerBase adds a lot of functionality to your custom endpoint, including:

• Basic request validation.

• Variance context for requests.

• Delivery API output caching, including the appropriate Vary response headers.

• Comprehensive Swagger documentation for property expansion and limiting.

The base class also gives convenient access to:

• The IApiPublishedContentCache, a specialized content cache tailored for the Delivery API. Among other things, it enforces the configuration of (dis)allowed output types.

• The IApiContentResponseBuilder for generating a content response format that conforms with the Delivery API. This includes support for property expansion and limiting.

A Delivery API endpoint for media

Similarly to content, a base class also exists for media endpoints; the MediaApiControllerBase. This base class provides much of the same functionality as the corresponding base class for content.

Here's an example of how to use the MediaApiControllerBase:

MediaDeliveryApiController.cs

using Asp.Versioning;
using Microsoft.AspNetCore.Mvc;
using Umbraco.Cms.Api.Delivery.Controllers.Media;
using Umbraco.Cms.Api.Delivery.Routing;
using Umbraco.Cms.Core.Models.DeliveryApi;
using Umbraco.Cms.Core.PublishedCache;
using Umbraco.Cms.Infrastructure.DeliveryApi;

namespace Umbraco.Docs;

[ApiVersion("2.0")]
[VersionedDeliveryApiRoute("custom")]
[ApiExplorerSettings(GroupName = "Custom")]
public class MediaDeliveryApiController : MediaApiControllerBase
{
    public MediaDeliveryApiController(
        IPublishedMediaCache publishedMediaCache,
        IApiMediaWithCropsResponseBuilder apiMediaWithCropsResponseBuilder)
        : base(publishedMediaCache, apiMediaWithCropsResponseBuilder)
    {
    }

    [HttpGet("media-api/{id:guid}")]
    [MapToApiVersion("2.0")]
    [ProducesResponseType(typeof(IApiMediaWithCropsResponse), StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
    [ProducesResponseType(StatusCodes.Status403Forbidden)]
    public async Task<IActionResult> Get(Guid id)
    {
        var media = await PublishedMediaCache.GetByIdAsync(id);
        return media is not null
            ? Ok(BuildApiMediaWithCrops(media))
            : NotFound();
    }
}