Ucommerce
  • Ucommerce Next Gen
    • Getting Started
      • Prerequisites
      • Licensing
      • Ucommerce Templates
      • Headless Template
      • MVC Template
    • Headless
      • Postman Collection
      • Headless API Authentication
        • Token endpoint - Authorization Header
        • Authorization Scopes
        • Refreshing the Access Token
      • Reference
        • Cart
        • Cart / Order Line Items
        • Shipment
        • Billing
        • Promotion Codes
        • Price Groups
        • Payment Methods
        • Countries
        • Shipping Methods
        • Catalogs
        • Cart Custom Properties
        • Line Item Custom Properties
        • Orders
        • Views for Cart modifying operations
      • Custom Headless APIs
      • Error Handling
      • Pagination
      • Deprecation
    • Backoffice Authentication
      • Microsoft Entra ID Example
      • Auth0 Authentication Example
    • Definitions
      • What is a Definition
    • Search and indexing
      • Configuration
      • Indexing
        • Index Definitions
        • Facets
        • Indexing Prices
        • Suggestions
        • Custom Data
      • Searching
    • Payment Providers
      • Stripe Provider Integration
      • Implementing a custom payment provider
    • Data Import
    • Miscellaneous
      • Media
      • Price Group Inheritance
      • Price Group Criteria
      • Soft Deletion Of Entities
      • Logging
      • OpenTelemetry
    • Extensions
      • Extending Pipelines
        • Order Processing Pipelines
        • Checkout Pipelines
      • Changing Service Behavior
        • Images
        • Content
      • Custom Headless APIs
      • Extend the Backoffice
        • Custom UI Components
      • Custom Editor UI
      • Custom Promotion Criteria
      • Custom Price Group Criteria
    • How-To
      • Migrate from Classic
        • Common database issues
      • Entities from code
        • Bootstrapping data on startup
        • Product Definitions & Fields
      • Discover pipelines and their tasks
      • Executing a pipeline
    • Integrations
      • Umbraco Media Delivery API
      • App Slices
        • Product Picker
  • Release Notes
  • Contact Us
Powered by GitBook
On this page
  • Prerequisites
  • Creating the API Controller
  • Creating the method
  • Complete example
  • Related Articles

Was this helpful?

  1. Ucommerce Next Gen
  2. Headless

Custom Headless APIs

PreviousViews for Cart modifying operationsNextError Handling

Last updated 1 year ago

Was this helpful?

Custom Headless APIs have two primary use cases:

  • For a fully headless solution, you will need custom APIs to serve catalogs, categories, and products to your client application.

  • For any special requirements that are not covered by the out-of-the-box APIs.

The goal is to create endpoints that give you freedom of implementation while respecting our authentication.

Prerequisites

  • Out-of-the-box Headless API available (for example, by using our as a starting point).

  • Secrets are set up for your stores, and the URI whitelist is correctly configured in the API Access part of the administration interface. You can .

Creating the API Controller

  • In your project, create a new Class and Inherit from Ucommerce.Web.WebSite.Controllers.HeadlessControllerBase

This will inherit our authentication, restricting its usage to only authenticated clients.

  • Add a route to your controller. It can match the out-of-the-box route as follows:

[Route("api/v1.0/products")]
  • In your controller's constructor, you can inject any components you may need in your implementation. For example,

private readonly IIndex<ProductSearchModel> _productIndex;

public ControllerName(IIndex<ProductSearchModel> productIndex)
{
    _productIndex = productIndex;
}

Creating the method

  • Create and annotate a new method with the HTTP method type and route.

[HttpGet]
[Route("")]
  • Headless API authentication happens on a per-store basis. You can resolve the StoreId from the claim as follows:

var storeGuid = Guid.Parse(User.FindFirstValue(ClaimTypes.NameIdentifier)
  • Complete your implementation and return the results to your client.

Complete example

For reference, here is a full controller example that will return products for a given Category:

using System.Globalization;
using System.Security.Authentication;
using System.Security.Claims;
using Microsoft.AspNetCore.Mvc;
using Ucommerce.Extensions.Search.Abstractions;
using Ucommerce.Extensions.Search.Abstractions.Models.IndexModels;
using Ucommerce.Extensions.Search.Abstractions.Models.SearchModels;
using Ucommerce.Web.WebSite.Controllers;

namespace project.CustomHeadlessControllers;

[Route("api/v1.0/products")]
public class HeadlessProductController : HeadlessControllerBase
{
    private readonly IIndex<ProductSearchModel> _productIndex;

    public HeadlessProductController(IIndex<ProductSearchModel> productIndex)
    {
        _productIndex = productIndex;
    }

    [HttpGet("")]
    public async Task<ActionResult<YourResponseModel>> GetProducts(
        [FromQuery] Guid categoryId,
        [FromQuery] string cultureCode,
        CancellationToken token)
    {
        var storeGuid =
            Guid.Parse(User.FindFirstValue(ClaimTypes.NameIdentifier) ?? throw new AuthenticationException());
        var culture = new CultureInfo(cultureCode);
        var products = _productIndex.AsSearchable(culture).Where(x => x.CategoryIds.Contains(categoryId));

        // 
        var productsResponse = new YourResponseModel()
        {
            Products = YourMapProducts(products)
        };

        return productsResponse;
    }

    // YourMapProducts implementation
}

Related Articles

For help with return types and choosing the right implementation details,

Standalone Template
learn about it here
visit Microsoft's documentation.
Headless