New document segments endpoint (#20088)

* Added `cultures` property to the Segment models

* Added new endpoint to return the segments of a specific document.

* Mark additional properties and methods as obsolete

* Small indentation fix

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

src/Umbraco.Cms.Api.Management/Controllers/Document/AvailableSegmentsController.cs

@@ -0,0 +1,85 @@
+using Asp.Versioning;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+using Umbraco.Cms.Api.Common.ViewModels.Pagination;
+using Umbraco.Cms.Api.Management.ViewModels.Segment;
+using Umbraco.Cms.Core;
+using Umbraco.Cms.Core.Actions;
+using Umbraco.Cms.Core.Mapping;
+using Umbraco.Cms.Core.Models;
+using Umbraco.Cms.Core.Security.Authorization;
+using Umbraco.Cms.Core.Services;
+using Umbraco.Cms.Core.Services.OperationStatus;
+using Umbraco.Cms.Web.Common.Authorization;
+using Umbraco.Extensions;
+
+namespace Umbraco.Cms.Api.Management.Controllers.Document;
+
+[Obsolete("This controller is temporary and will be removed in a future release (planned for v20). A more permanent solution will follow.")]
+[ApiVersion("1.0")]
+public class AvailableSegmentsController : DocumentControllerBase
+{
+    private readonly IAuthorizationService _authorizationService;
+    private readonly ISegmentService _segmentService;
+    private readonly IUmbracoMapper _umbracoMapper;
+
+    public AvailableSegmentsController(
+        IAuthorizationService authorizationService,
+        ISegmentService segmentService,
+        IUmbracoMapper umbracoMapper)
+    {
+        _authorizationService = authorizationService;
+        _segmentService = segmentService;
+        _umbracoMapper = umbracoMapper;
+    }
+
+    [HttpGet("{id:guid}/available-segment-options")]
+    [MapToApiVersion("1.0")]
+    [ProducesResponseType(typeof(PagedViewModel<SegmentResponseModel>), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
+    public async Task<IActionResult> GetAvailableSegmentOptions(
+        Guid id,
+        CancellationToken cancellationToken,
+        int skip = 0,
+        int take = 100)
+    {
+        AuthorizationResult authorizationResult = await _authorizationService.AuthorizeResourceAsync(
+            User,
+            ContentPermissionResource.WithKeys(ActionBrowse.ActionLetter, id),
+            AuthorizationPolicies.ContentPermissionByResource);
+
+        if (!authorizationResult.Succeeded)
+        {
+            return Forbidden();
+        }
+
+        Attempt<PagedModel<Core.Models.Segment>?, SegmentOperationStatus> pagedAttempt =
+            await _segmentService.GetPagedSegmentsForDocumentAsync(id, skip, take);
+
+        if (pagedAttempt.Success is false)
+        {
+            return MapFailure(pagedAttempt.Status);
+        }
+
+        var viewModel = new PagedViewModel<SegmentResponseModel>
+        {
+            Items = _umbracoMapper.MapEnumerable<Core.Models.Segment, SegmentResponseModel>(pagedAttempt.Result!.Items),
+            Total = pagedAttempt.Result!.Total,
+        };
+
+        return Ok(viewModel);
+    }
+
+    private IActionResult MapFailure(SegmentOperationStatus status)
+        => OperationStatusResult(
+            status,
+            problemDetailsBuilder => status switch
+            {
+                _ => StatusCode(
+                    StatusCodes.Status500InternalServerError,
+                    problemDetailsBuilder
+                        .WithTitle("Unknown segment operation status.")
+                        .Build()),
+            });
+}

src/Umbraco.Cms.Api.Management/Mapping/Segment/SegmentMapDefinition.cs

@@ -5,12 +5,15 @@ namespace Umbraco.Cms.Api.Management.Mapping.Segment;
 
 public class SegmentMapDefinition : IMapDefinition
 {
-    public void DefineMaps(IUmbracoMapper mapper) => mapper.Define<Core.Models.Segment, SegmentResponseModel>((_, _) => new SegmentResponseModel { Name = string.Empty, Alias = string.Empty }, Map);
+    public void DefineMaps(IUmbracoMapper mapper) => mapper.Define<Core.Models.Segment, SegmentResponseModel>(
+        (_, _) => new SegmentResponseModel { Name = string.Empty, Alias = string.Empty, Cultures = null },
+        Map);
 
     // Umbraco.Code.MapAll
     private static void Map(Core.Models.Segment source, SegmentResponseModel target, MapperContext context)
     {
         target.Name = source.Name;
         target.Alias = source.Alias;
+        target.Cultures = source.Cultures;
     }
 }

src/Umbraco.Cms.Api.Management/ViewModels/Segment/SegmentResponseModel.cs

@@ -1,5 +1,3 @@
-using System.ComponentModel.DataAnnotations;
-
 namespace Umbraco.Cms.Api.Management.ViewModels.Segment;
 
 public class SegmentResponseModel
@@ -7,4 +5,7 @@ public class SegmentResponseModel
     public required string Name { get; set; } = string.Empty;
 
     public required string Alias { get; set; } = string.Empty;
+
+    [Obsolete("This property is temporary and will be removed in a future release (planned for v20). A more permanent solution will follow.")]
+    public IEnumerable<string>? Cultures { get; set; } = null;
 }

src/Umbraco.Core/Models/Segment.cs

@@ -5,4 +5,7 @@ public class Segment
     public required string Name { get; set; }
 
     public required string Alias { get; set; }
+
+    [Obsolete("This property is temporary and will be removed in a future release (planned for v20). A more permanent solution will follow.")]
+    public IEnumerable<string>? Cultures { get; set; } = null;
 }

src/Umbraco.Core/Services/ISegmentService.cs

@@ -5,5 +5,27 @@ namespace Umbraco.Cms.Core.Services;
 
 public interface ISegmentService
 {
-    Task<Attempt<PagedModel<Segment>?, SegmentOperationStatus>> GetPagedSegmentsAsync(int skip = 0, int take = 100);
+    /// <summary>
+    ///    Gets a paged list of segments.
+    /// </summary>
+    /// <param name="skip">The number of items to skip.</param>
+    /// <param name="take">The number of items to take.</param>
+    /// <returns>The paged list of segments.</returns>
+    Task<Attempt<PagedModel<Segment>?, SegmentOperationStatus>> GetPagedSegmentsAsync(
+        int skip = 0,
+        int take = 100);
+
+    /// <summary>
+    ///   Gets a paged list of segments for a specific document.
+    /// </summary>
+    /// <param name="id">The document unique identifier.</param>
+    /// <param name="skip">The number of items to skip.</param>
+    /// <param name="take">The number of items to take.</param>
+    /// <returns>The paged list of segments.</returns>
+    [Obsolete("This method is temporary and will be removed in a future release (planned for v20). A more permanent solution will follow.")]
+    Task<Attempt<PagedModel<Segment>?, SegmentOperationStatus>> GetPagedSegmentsForDocumentAsync(
+        Guid id,
+        int skip = 0,
+        int take = 100)
+        => GetPagedSegmentsAsync(skip, take);
 }