Umbraco Media Delivery API

Leverage Umbraco as your DAM

In this guide, we'll use Umbraco as a Digital Asset Management system and integrate it with Ucommerce. We'll use the Umbraco Media Delivery API to retrieve the information we need.

Here's a look at the final result:

A look at how Umbraco can be leveraged as a DAM system for Ucommerce

Prerequisites

Before you get started, please make sure both Umbraco templates and Ucommerce templates are installed.

Setup Projects

Umbraco

Create a new project using the Umbraco template. Make sure both delivery API and media is enabled in appsettings.json:

"DeliveryApi": {
  "Enabled": true,
  "PublicAccess": true,
  "Media": {
    "Enabled": true,
    "PublicAccess": true
  }
}

PublicAccess should not be true in a publicly available environment

When Umbraco is installed, take it for a spin and add some images to the Media library:

Media added to Umbraco

Ucommerce

Create a new project using the Ucommerce Headless template.

Generate the Umbraco Client

To make Ucommerce communicate with Umbraco, we need a client to handle the REST calls to the Umbraco Delivery API. You can either code this yourself or use a tool to generate it. For this guide, we're going to use Microsoft Kiota to generate it for us.

First, install Microsoft Kiota as a .Net tool or as a VS Code extension.

Second, use Kiota to generate a client from the Umbraco Delivery API Specification using either the command line (see below) or the VS Code plugin UI.

kiota generate 
    --openapi "https://localhost:{yourUmbracoPortNumber}/umbraco/swagger/delivery/swagger.json" \
    --language CSharp \
    --additional-data false \
    --class-name UmbracoClient \
    --namespace-name UcommerceTest.Integrations.Umbraco \
    --output ./Umbraco

The Umbraco Delivery API Specification can be found on https://localhost:{yourUmbracoPortNumber}/umbraco/swagger/delivery/swagger.json

See Optional parameters for more details on the command

Third, add the needed Kiota dependencies to the Ucommerce project.

Run kiota info --language CSharp to get a list of dependencies needed.

The csproj file should look similar to this:

<ItemGroup>
    <PackageReference Include="Microsoft.Kiota.Abstractions" Version="1.14.0" />
    <PackageReference Include="Microsoft.Kiota.Http.HttpClientLibrary" Version="1.14.0" />
    <PackageReference Include="Microsoft.Kiota.Serialization.Form" Version="1.14.0" />
    <PackageReference Include="Microsoft.Kiota.Serialization.Json" Version="1.14.0" />
    <PackageReference Include="Microsoft.Kiota.Serialization.Multipart" Version="1.14.0" />
    <PackageReference Include="Microsoft.Kiota.Serialization.Text" Version="1.14.0" />
    <PackageReference Include="Ucommerce.Web.BackOffice" Version="10.8.0" />
    <PackageReference Include="Ucommerce.Web.WebSite" Version="10.8.0" />
    <PackageReference Include="Ucommerce.Search.Elastic" Version="10.8.0" />
</ItemGroup>

Implementing UmbracoImageService.cs

In the Ucommerce project, create a new class UmbracoImageService that inherits from IImageService. This class is responsible for mapping between the UmbracoClient created previously and Ucommerce. See Images for more details.

Below is a complete example:

using System.Collections.Immutable;
using Ucommerce.Web.Infrastructure;
using Ucommerce.Web.Infrastructure.Core;
using Ucommerce.Web.Infrastructure.Core.Models;
using UcommerceTest.Integrations.Umbraco;
using UcommerceTest.Integrations.Umbraco.Models;

namespace UcommerceTest;

public class UmbracoImageService(UmbracoClient kiotaClient, UmbracoSettings umbracoSettings) : IImageService
{
    public async Task<IImmutableList<Content>> Get(
        string? parentId = null, 
        int startAt = 0, 
        int limit = 30,
        CancellationToken? token = null)
    {
        parentId ??= "/";
        var items =
            await kiotaClient.Umbraco.Delivery.Api.V2.Media.GetAsync(
                request =>
                {
                    request.QueryParameters.Fetch = $"children:{parentId}";
                    request.QueryParameters.Skip = startAt;
                    request.QueryParameters.Take = limit;
                }, token.GetValueOrDefault());

        return items?.Items?
            .Select(item => MapMedia(parentId, item))
            .ToImmutableList() ?? ImmutableList<Content>.Empty;
    }

    public async Task<Content> GetById(string? id, CancellationToken token)
    {
        if (string.IsNullOrEmpty(id))
        {
            return ImageNotFound();
        }

        var item = await kiotaClient.Umbraco.Delivery.Api.V2.Media.Item[Guid.Parse(id)]
            .GetAsync(cancellationToken: token);

        return item is null ? ImageNotFound() : MapMedia(null, item);
    }
    
    public async Task<IImmutableList<Content>> GetByIds(
        IImmutableList<string> ids, 
        CancellationToken? token = null)
    {
        var guids = ids.Select(Guid.Parse).Cast<Guid?>().ToArray();
        var items = await kiotaClient.Umbraco.Delivery.Api.V2.Media.Items.GetAsync(
            request => request.QueryParameters.Id = guids, token.GetValueOrDefault()) ?? [];

        return items
            .Select(item => MapMedia(null, item))
            .ToImmutableList();
    }

    /// <summary>
    /// Maps the response model to a Content object
    /// </summary>
    private Content MapMedia(
        string? parentId, 
        ApiMediaWithCropsResponseModel responseModel) => new()
    {
        Name = responseModel.Name ?? "No name",
        NodeType = responseModel.MediaType!.Equals("Folder") ? Constants.ImagePicker.Folder : Constants.ImagePicker.Image,
        Url = string.IsNullOrWhiteSpace(responseModel.Url) ? "No URL" : CombineUris(umbracoSettings.BaseUrl, responseModel.Url),
        Id = responseModel.Id?.ToString() ?? "No ID",
        ParentId = parentId,
        Icon = responseModel.MediaType!.Equals("Folder") ? "icon-folder" : "icon-picture",
        ChildrenCount = null
    };

    /// <summary>
    /// Gives a default image when the request image could not be found
    /// </summary>
    private static Content ImageNotFound()
    {
        return new Content
        {
            Id = "image-not-found",
            Name = "image-not-found.png",
            Url = "ImageNotFoundImageURL",
            NodeType = Constants.ImagePicker.Image
        };
    }
    
    /// <summary>
    /// Combines two URIs into one making sure there is only one '/' between them
    /// </summary>
    private static string CombineUris(string uri1, string uri2)
    {
        uri1 = uri1.TrimEnd('/');
        uri2 = uri2.TrimStart('/');
        return $"{uri1}/{uri2}";
    }
}

Each method is straightforward: Get the necessary data from Umbraco using the UmbracoClient, map the data to fit Ucommerce, and return the result.

Note that the ChildrenCount is set to null. This is because the Umbraco Delivery API does not contain any information on the number of children for a given node. See Media for more details on what that means.

Tying everything together

The last step needed is to set up UmbracoClient and UmbracoImageService in the Ucommerce project. Because the Umbraco Delivery API does not contain any information on the base URL, we'll have to set that up manually. As you might have noticed, we also need the base URL when mapping the URL as Umbraco returns only relative URLs.

UmbracoSettings.cs

The settings object is a single line of code:

public record UmbracoSettings(string BaseUrl);

UmbracoModuleExtensions.cs

To make the integration reusable, we suggest using an extension method for every module:

public static class UmbracoModuleExtensions
{
    public static IUcommerceBuilder AddUmbracoIntegration(
        this IUcommerceBuilder builder, 
        IConfiguration configuration)
    {
        
        var umbracoSettings = configuration.GetRequiredSection("Umbraco").Get<UmbracoSettings>();
        if(umbracoSettings is null)
        {
            throw new InvalidOperationException("Umbraco settings are missing");
        }
        builder.Services.AddSingleton(umbracoSettings);
        builder.Services.AddSingleton(new UmbracoClient(
            new HttpClientRequestAdapter(new AnonymousAuthenticationProvider())
            {
                BaseUrl = umbracoSettings.BaseUrl
            }));
        builder.Services.AddUnique<IImageService, UmbracoImageService>();
        return builder;
    }
}

Remember to use a different authentication provider when your Umbraco instance is not publicly accessible.

For the configuration to work, add the base URL to the following path in appsettings.json: Umbraco:BaseUrl:

"Umbraco":
{
  "BaseUrl": "https://localhost:{yourUmbracoPortNumber}"
}

The final step is to call AddUmbracoIntegration in Program.cs:

// Set up services
builder.Services.AddUcommerce(builder.Configuration)
    ...
    .AddUmbracoIntegration(builder.Configuration)
    .Build();

Congratulations! Ucommerce is now able to get images from Umbraco!

See it in action

Now, try taking the Ucommerce project for a spin and select an image for a product.