Delivery API: Query controller (#14041)

* Initial commit

* Custom ContentAPIFieldDefinitionCollection

* Make index IUmbracoContentIndex

* Add querying for children by parent id (key)

* Add missing interface

* Adding querying endpoint

* Test code

* Compose unpublishedValueSet, so that you get the correct data in the ContentAPI index

* Renaming

* Fix ancestorKeys index values

* Adding IApiQueryExtensionService to be able to query the ContentAPI index in a generic way

* Fix IApiQueryService and clean up QueryContentApiController using it

* Support querying for path

* Fix content API indexing

* Fix default sorting

* Implement concrete QueryOption implementations

* Introduce new ExecuteQuery that uses the Core OptionHandlers

* Implement ExecuteQuery

* Change ExecuteQuery signature and implementation

* Implement demo sorting and fetching

* Add query option handlers and collection builder for them

* Cleanup

* Revert "Conditionally enabling the delivery API + add protection and preview support + refactor all services to be singletons + ensure no-op implementations for all required services (#13992)"

This reverts commit 78e1f74.

* Revert "Delivery API: Content routing and structure (#13984)"

This reverts commit a0292ae.

* Revert "Fix multi URL picker value converter trying to access disposed objects in edge cases"

This reverts commit 6b7c37a.

* Revert "Conditionally enabling the delivery API + add protection and preview support + refactor all services to be singletons + ensure no-op implementations for all required services (#13992)"

This reverts commit 78e1f74.

* Revert "Delivery API: Content routing and structure (#13984)"

This reverts commit a0292ae.

* Revert "Fix multi URL picker value converter trying to access disposed objects in edge cases"

This reverts commit 6b7c37a.

* Fix multi URL picker value converter trying to access disposed objects in edge cases

* Delivery API: Content routing and structure (#13984)

* Introduce content route instead of content path, rename and rework start item (previously start node) handling

* Strip out start node path in generated route path

* Make the start-item header take precedence over the request domain

* Conditionally enabling the delivery API + add protection and preview support + refactor all services to be singletons + ensure no-op implementations for all required services (#13992)

* Test commit

* Refactored interfaces for the query handlers and for the selectors (that will handle the value of the fetch query option)

* Implemented a base class for the query options

* Refactored the names of the selectors and made use of the base class

* Refactored the ApiQueryService

* Refactored the QueryContentApiController.cs

* Conditionally enabling the delivery API + add protection and preview support + refactor all services to be singletons + ensure no-op implementations for all required services (#13992)

* Fixing merge gone wrong

* Fix multi URL picker value converter trying to access disposed objects in edge cases

* Delivery API: Content routing and structure (#13984)

* Introduce content route instead of content path, rename and rework start item (previously start node) handling

* Strip out start node path in generated route path

* Make the start-item header take precedence over the request domain

* Conditionally enabling the delivery API + add protection and preview support + refactor all services to be singletons + ensure no-op implementations for all required services (#13992)

* Make fetching work with the new setup

* Moving files to dedicated folders

* Removing ? for array

* Rename selector query method

* Implement FilterHandler and some filters

* Implement SortHandler and sort some sorts

* Refactoring

* Adding more fields to index due to querying

* Appending filtering and sorting queries

* Implementing a new ISelectorHandler without Examine types

* Re-implementing the collection to have a dedicated one for the selectors

* Implementing a new IFilterHandler without Examine types & refactoring the filters implementing it

* Adding a new collection dedicated to filters

* Renaming the old collection

* Implementing a new ISortHandler without Examine types & refactoring the sorts implementing it

* Adding a new collection for the sorts & adding all collections to UmbracoBuilder.Collections

* Refactoring the service to use the new collections and types

* Refactoring the fields in ContentApiFieldDefinitionCollection

* Remove nullability in Handlers

* Don't return null for selector

* Add TODO for having the filters support negation

* Changing the SortType to FieldType with our custom types on the SortOption

* Fix AncestorsSelector

* Fix ApiQueryService

* Documentation

* Fix Swagger docs

* Refactor the QueryContentApiController

* Adding handling for the IApiContentResponse in the JsonTypeResolver

* Refactor the service to use a safe fallback value in Examine queries

* Adding Noop for the IApiQueryService

* Cleanup

* Remove comment

* Fix name field for indexing

* Don't inherit QueryOptionBase in filters

* Fix casing for API index constant + swap FIXME with TODO

* Add TODO for handling missing fetch with start-item header

* Rename query handler parameters to not leak source (i.e. query string)

---------

Co-authored-by: kjac <[email protected]>
Co-authored-by: Elitsa <>
Co-authored-by: Zeegaan <[email protected]>

src/Umbraco.Cms.Api.Content/Controllers/ByIdContentApiController.cs

@@ -1,6 +1,7 @@
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using Umbraco.Cms.Core.ContentApi;
+using Umbraco.Cms.Core.Models.ContentApi;
 using Umbraco.Cms.Core.Models.PublishedContent;
 
 namespace Umbraco.Cms.Api.Content.Controllers;
@@ -19,8 +20,7 @@ public ByIdContentApiController(IApiPublishedContentCache apiPublishedContentCac
     /// <returns>The content item or not found result.</returns>
     [HttpGet("item/{id:guid}")]
     [MapToApiVersion("1.0")]
-    [ProducesResponseType(typeof(IApiContentResponseBuilder), StatusCodes.Status200OK)]
-    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(typeof(IApiContentResponse), StatusCodes.Status200OK)]
     [ProducesResponseType(StatusCodes.Status404NotFound)]
     public async Task<IActionResult> ById(Guid id)
     {

src/Umbraco.Cms.Api.Content/Controllers/ByRouteContentApiController.cs

@@ -33,8 +33,7 @@ public ByRouteContentApiController(
     /// <returns>The content item or not found result.</returns>
     [HttpGet("item/{*path}")]
     [MapToApiVersion("1.0")]
-    [ProducesResponseType(typeof(IApiContentResponseBuilder), StatusCodes.Status200OK)]
-    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(typeof(IApiContentResponse), StatusCodes.Status200OK)]
     [ProducesResponseType(StatusCodes.Status404NotFound)]
     public async Task<IActionResult> ByRoute(string path = "/")
     {

src/Umbraco.Cms.Api.Content/Controllers/QueryContentApiController.cs

@@ -0,0 +1,39 @@
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+using Umbraco.Cms.Core.ContentApi;
+using Umbraco.Cms.Core.Models.ContentApi;
+using Umbraco.Cms.Core.Models.PublishedContent;
+
+namespace Umbraco.Cms.Api.Content.Controllers;
+
+public class QueryContentApiController : ContentApiControllerBase
+{
+    private readonly IApiQueryService _apiQueryService;
+
+    public QueryContentApiController(
+        IApiPublishedContentCache apiPublishedContentCache,
+        IApiContentResponseBuilder apiContentResponseBuilderBuilder,
+        IApiQueryService apiQueryService)
+        : base(apiPublishedContentCache, apiContentResponseBuilderBuilder)
+        => _apiQueryService = apiQueryService;
+
+    /// <summary>
+    ///     Gets content item(s) from query.
+    /// </summary>
+    /// <param name="fetch">Optional fetch query parameter value.</param>
+    /// <param name="filter">Optional filter query parameters values.</param>
+    /// <param name="sort">Optional sort query parameters values.</param>
+    /// <returns>The content item(s) or empty collection.</returns>
+    [HttpGet]
+    [MapToApiVersion("1.0")]
+    [ProducesResponseType(typeof(IEnumerable<IApiContentResponse>), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    public async Task<IActionResult> Query(string? fetch, [FromQuery] string[] filter, [FromQuery] string[] sort)
+    {
+        IEnumerable<Guid> ids = _apiQueryService.ExecuteQuery(fetch, filter, sort);
+        IEnumerable<IPublishedContent> contentItems = ApiPublishedContentCache.GetByIds(ids);
+        IEnumerable<IApiContentResponse> results = contentItems.Select(ApiContentResponseBuilder.Build);
+
+        return await Task.FromResult(Ok(results));
+    }
+}

src/Umbraco.Cms.Api.Content/DependencyInjection/UmbracoBuilderExtensions.cs

@@ -26,6 +26,7 @@ public static IUmbracoBuilder AddContentApi(this IUmbracoBuilder builder)
         builder.Services.AddSingleton<IOutputExpansionStrategyAccessor, RequestContextOutputExpansionStrategyAccessor>();
         builder.Services.AddSingleton<IRequestStartItemProviderAccessor, RequestContextRequestStartItemProviderAccessor>();
         builder.Services.AddSingleton<IApiAccessService, ApiAccessService>();
+        builder.Services.AddSingleton<IApiQueryService, ApiQueryService>();
 
         builder
             .Services

src/Umbraco.Cms.Api.Content/Json/ContentApiJsonTypeResolver.cs

@@ -13,18 +13,22 @@ public override JsonTypeInfo GetTypeInfo(Type type, JsonSerializerOptions option
     {
         JsonTypeInfo jsonTypeInfo = base.GetTypeInfo(type, options);
 
-        if (jsonTypeInfo.Type == typeof(IApiContent))
-        {
-            jsonTypeInfo.PolymorphismOptions = new JsonPolymorphismOptions
-            {
-                UnknownDerivedTypeHandling = JsonUnknownDerivedTypeHandling.FailSerialization,
-                DerivedTypes =
-                {
-                    new JsonDerivedType(typeof(ApiContent))
-                }
-            };
+         if (jsonTypeInfo.Type == typeof(IApiContent))
+         {
+             ConfigureJsonPolymorphismOptions(jsonTypeInfo, typeof(ApiContent));
+         }
+         else if (jsonTypeInfo.Type == typeof(IApiContentResponse))
+         {
+             ConfigureJsonPolymorphismOptions(jsonTypeInfo, typeof(ApiContentResponse));
         }
 
         return jsonTypeInfo;
     }
+
+    private void ConfigureJsonPolymorphismOptions(JsonTypeInfo jsonTypeInfo, Type derivedType)
+        => jsonTypeInfo.PolymorphismOptions = new JsonPolymorphismOptions
+        {
+            UnknownDerivedTypeHandling = JsonUnknownDerivedTypeHandling.FailSerialization,
+            DerivedTypes = { new JsonDerivedType(derivedType) }
+        };
 }

src/Umbraco.Cms.Api.Content/Querying/Filters/ContentTypeFilter.cs

@@ -0,0 +1,38 @@
+using Umbraco.Cms.Core.ContentApi;
+
+namespace Umbraco.Cms.Api.Content.Querying.Filters;
+
+internal sealed class ContentTypeFilter : IFilterHandler
+{
+    private const string ContentTypeSpecifier = "contentType:";
+
+    /// <inheritdoc />
+    public bool CanHandle(string query)
+        => query.StartsWith(ContentTypeSpecifier, StringComparison.OrdinalIgnoreCase);
+
+    /// <inheritdoc/>
+    public FilterOption BuildFilterOption(string filter)
+    {
+        var alias = filter.Substring(ContentTypeSpecifier.Length);
+
+        var filterOption = new FilterOption
+        {
+            FieldName = "__NodeTypeAlias",
+            Value = string.Empty
+        };
+
+        // TODO: do we support negation?
+        if (alias.StartsWith('!'))
+        {
+            filterOption.Value = alias.Substring(1);
+            filterOption.Operator = FilterOperation.IsNot;
+        }
+        else
+        {
+            filterOption.Value = alias;
+            filterOption.Operator = FilterOperation.Is;
+        }
+
+        return filterOption;
+    }
+}

src/Umbraco.Cms.Api.Content/Querying/Filters/NameFilter.cs

@@ -0,0 +1,38 @@
+using Umbraco.Cms.Core.ContentApi;
+
+namespace Umbraco.Cms.Api.Content.Querying.Filters;
+
+internal sealed class NameFilter : IFilterHandler
+{
+    private const string NameSpecifier = "name:";
+
+    /// <inheritdoc />
+    public bool CanHandle(string query)
+        => query.StartsWith(NameSpecifier, StringComparison.OrdinalIgnoreCase);
+
+    /// <inheritdoc/>
+    public FilterOption BuildFilterOption(string filter)
+    {
+        var value = filter.Substring(NameSpecifier.Length);
+
+        var filterOption = new FilterOption
+        {
+            FieldName = "name",
+            Value = string.Empty
+        };
+
+        // TODO: do we support negation?
+        if (value.StartsWith('!'))
+        {
+            filterOption.Value = value.Substring(1);
+            filterOption.Operator = FilterOperation.IsNot;
+        }
+        else
+        {
+            filterOption.Value = value;
+            filterOption.Operator = FilterOperation.Is;
+        }
+
+        return filterOption;
+    }
+}

src/Umbraco.Cms.Api.Content/Querying/QueryOptionBase.cs

@@ -0,0 +1,39 @@
+using System;
+using Umbraco.Cms.Core.ContentApi;
+using Umbraco.Cms.Core.Models.PublishedContent;
+using Umbraco.Cms.Core.PublishedCache;
+
+namespace Umbraco.Cms.Api.Content.Querying;
+
+public abstract class QueryOptionBase
+{
+    private readonly IPublishedSnapshotAccessor _publishedSnapshotAccessor;
+    private readonly IRequestRoutingService _requestRoutingService;
+
+    public QueryOptionBase(IPublishedSnapshotAccessor publishedSnapshotAccessor,
+        IRequestRoutingService requestRoutingService)
+    {
+        _publishedSnapshotAccessor = publishedSnapshotAccessor;
+        _requestRoutingService = requestRoutingService;
+    }
+
+    public Guid? GetGuidFromQuery(string queryStringValue)
+    {
+        if (Guid.TryParse(queryStringValue, out Guid id))
+        {
+            return id;
+        }
+
+        if (!_publishedSnapshotAccessor.TryGetPublishedSnapshot(out IPublishedSnapshot? publishedSnapshot) ||
+            publishedSnapshot?.Content is null)
+        {
+            return null;
+        }
+
+        // Check if the passed value is a path of a content item
+        var contentRoute = _requestRoutingService.GetContentRoute(queryStringValue);
+        IPublishedContent? contentItem = publishedSnapshot.Content.GetByRoute(contentRoute);
+
+        return contentItem?.Key;
+    }
+}

src/Umbraco.Cms.Api.Content/Querying/Selectors/AncestorsSelector.cs

@@ -0,0 +1,51 @@
+using Umbraco.Cms.Core.ContentApi;
+using Umbraco.Cms.Core.Models.PublishedContent;
+using Umbraco.Cms.Core.PublishedCache;
+using Umbraco.Extensions;
+
+namespace Umbraco.Cms.Api.Content.Querying.Selectors;
+
+internal sealed class AncestorsSelector : QueryOptionBase, ISelectorHandler
+{
+    private const string AncestorsSpecifier = "ancestors:";
+    private readonly IPublishedSnapshotAccessor _publishedSnapshotAccessor;
+
+    public AncestorsSelector(IPublishedSnapshotAccessor publishedSnapshotAccessor, IRequestRoutingService requestRoutingService)
+        : base(publishedSnapshotAccessor, requestRoutingService) =>
+        _publishedSnapshotAccessor = publishedSnapshotAccessor;
+
+    /// <inheritdoc />
+    public bool CanHandle(string query)
+        => query.StartsWith(AncestorsSpecifier, StringComparison.OrdinalIgnoreCase);
+
+    /// <inheritdoc/>
+    public SelectorOption BuildSelectorOption(string selector)
+    {
+        var fieldValue = selector.Substring(AncestorsSpecifier.Length);
+        Guid? id = GetGuidFromQuery(fieldValue);
+
+        if (id is null ||
+            !_publishedSnapshotAccessor.TryGetPublishedSnapshot(out IPublishedSnapshot? publishedSnapshot) ||
+            publishedSnapshot?.Content is null)
+        {
+            // Setting the Value to "" since that would yield no results.
+            // It won't be appropriate to return null here since if we reached this,
+            // it means that CanHandle() returned true, meaning that this Selector should be able to handle the selector value
+            return new SelectorOption
+            {
+                FieldName = "id",
+                Value = string.Empty
+            };
+        }
+
+        // With the previous check we made sure that if we reach this, we already made sure that there is a valid content item
+        IPublishedContent contentItem = publishedSnapshot.Content.GetById((Guid)id)!; // so it can't be null
+        IEnumerable<Guid> ancestorKeys = contentItem.Ancestors().Select(a => a.Key);
+
+        return new SelectorOption
+        {
+            FieldName = "id",
+            Value = string.Join(" ", ancestorKeys)
+        };
+    }
+}

src/Umbraco.Cms.Api.Content/Querying/Selectors/ChildrenSelector.cs

@@ -0,0 +1,31 @@
+using Umbraco.Cms.Core.ContentApi;
+using Umbraco.Cms.Core.PublishedCache;
+
+namespace Umbraco.Cms.Api.Content.Querying.Selectors;
+
+internal sealed class ChildrenSelector : QueryOptionBase, ISelectorHandler
+{
+    private const string ChildrenSpecifier = "children:";
+
+    public ChildrenSelector(IPublishedSnapshotAccessor publishedSnapshotAccessor, IRequestRoutingService requestRoutingService)
+        : base(publishedSnapshotAccessor, requestRoutingService)
+    {
+    }
+
+    /// <inheritdoc />
+    public bool CanHandle(string query)
+        => query.StartsWith(ChildrenSpecifier, StringComparison.OrdinalIgnoreCase);
+
+    /// <inheritdoc/>
+    public SelectorOption BuildSelectorOption(string selector)
+    {
+        var fieldValue = selector.Substring(ChildrenSpecifier.Length);
+        Guid? id = GetGuidFromQuery(fieldValue);
+
+        return new SelectorOption
+        {
+            FieldName = "parentKey",
+            Value = id.ToString() ?? string.Empty
+        };
+    }
+}

src/Umbraco.Cms.Api.Content/Querying/Selectors/DescendantsSelector.cs

@@ -0,0 +1,32 @@
+using Umbraco.Cms.Core.ContentApi;
+using Umbraco.Cms.Core.PublishedCache;
+
+namespace Umbraco.Cms.Api.Content.Querying.Selectors;
+
+internal sealed class DescendantsSelector : QueryOptionBase, ISelectorHandler
+{
+    private const string DescendantsSpecifier = "descendants:";
+
+    public DescendantsSelector(IPublishedSnapshotAccessor publishedSnapshotAccessor,
+        IRequestRoutingService requestRoutingService)
+        : base(publishedSnapshotAccessor, requestRoutingService)
+    {
+    }
+
+    /// <inheritdoc />
+    public bool CanHandle(string query)
+        => query.StartsWith(DescendantsSpecifier, StringComparison.OrdinalIgnoreCase);
+
+    /// <inheritdoc/>
+    public SelectorOption BuildSelectorOption(string selector)
+    {
+        var fieldValue = selector.Substring(DescendantsSpecifier.Length);
+        Guid? id = GetGuidFromQuery(fieldValue);
+
+        return new SelectorOption
+        {
+            FieldName = "ancestorKeys",
+            Value = id.ToString() ?? string.Empty
+        };
+    }
+}

src/Umbraco.Cms.Api.Content/Querying/Sorts/LevelSort.cs

@@ -0,0 +1,26 @@
+using Umbraco.Cms.Core;
+using Umbraco.Cms.Core.ContentApi;
+
+namespace Umbraco.Cms.Api.Content.Querying.Sorts;
+
+internal sealed class LevelSort : ISortHandler
+{
+    private const string SortOptionSpecifier = "level:";
+
+    /// <inheritdoc />
+    public bool CanHandle(string query)
+        => query.StartsWith(SortOptionSpecifier, StringComparison.OrdinalIgnoreCase);
+
+    /// <inheritdoc/>
+    public SortOption BuildSortOption(string sort)
+    {
+        var sortDirection = sort.Substring(SortOptionSpecifier.Length);
+
+        return new SortOption
+        {
+            FieldName = "level",
+            Direction = sortDirection.StartsWith("asc") ? Direction.Ascending : Direction.Descending,
+            FieldType = FieldType.Number
+        };
+    }
+}

src/Umbraco.Cms.Api.Content/Querying/Sorts/NameSort.cs

@@ -0,0 +1,26 @@
+using Umbraco.Cms.Core;
+using Umbraco.Cms.Core.ContentApi;
+
+namespace Umbraco.Cms.Api.Content.Querying.Sorts;
+
+internal sealed class NameSort : ISortHandler
+{
+    private const string SortOptionSpecifier = "name:";
+
+    /// <inheritdoc />
+    public bool CanHandle(string query)
+        => query.StartsWith(SortOptionSpecifier, StringComparison.OrdinalIgnoreCase);
+
+    /// <inheritdoc/>
+    public SortOption BuildSortOption(string sort)
+    {
+        var sortDirection = sort.Substring(SortOptionSpecifier.Length);
+
+        return new SortOption
+        {
+            FieldName = "name",
+            Direction = sortDirection.StartsWith("asc") ? Direction.Ascending : Direction.Descending,
+            FieldType = FieldType.String
+        };
+    }
+}