Ucommerce API Overview

Learn how the Ucommerce APIs are structured and what to expect from working with the top-level APIs of the platform.

The 80/20 APIs

The top-level APIs of Ucommerce are lovingly called 80/20 APIs because they are designed for very specific purposes: ease of use, and discoverability, which means that they are not designed for ultimate flexibility.

They are appropriate for maybe 80% of what you want to do when building an online store, but for the last 20% or to get more flexibility, you will have to use a lower level API.

The premise for the platform is that you can make Ucommerce do whatever you need. If you can't find what you need, you can always move down a level of abstraction. This is especially useful when you need to override behaviors of the API for more advanced scenarios.

The 80/20 APIs are structured into two different categories:

• Libraries
• Context classes

Libraries are used to do operations on the front-end such as search, apply promocodes or add products to the basket.

Context classes are used to retrieve the current context of the site such as the current store, category or basket.

Libraries are context aware and will use the context to make it simpler to call methods on them, e.g. you don't have to specify which customer to get the basket for as that's determined by the order context. However if you need them in a state where they do not look at a context (because there won't be one) you can simply supply optional parameters for the API.

Libraries

All the Libraries for doing various operations are located in the assembly UCommerce.Api.

Libraries needs to be resolved either via constructor / property injection or via Objectfactory. In a web api controller it can look something like this:

    
    using System.Web.Http;
    using Ucommerce.Api;
    using Ucommerce.Infrastructure;
    
    
    public class ApiOverview : ApiController
    {
    
        private readonly Ucommerce.Api.ICatalogContext _catalogContext;
        private readonly Ucommerce.Api.ICatalogLibrary _catalogLibrary;
    
        //using ObjectFactory to resolve your dependency 
        public ApiOverview()
        {
            _catalogLibrary = Ucommerce.Infrastructure.ObjectFactory.Instance.Resolve<Ucommerce.Api.ICatalogLibrary>();
        }   
        
        //if bridge between IOC and MVC / Web API exists
        public ApiOverview(Ucommerce.Api.ICatalogContext catalogContext)
        {
            _catalogContext = catalogContext;
        }
    }
    
    

Available libraries include the following:

    
    var catalogLibrary = Ucommerce.Infrastructure.ObjectFactory.Instance.Resolve<Ucommerce.Api.ICatalogLibrary>();
    
    

Using libraries is meant to be as straightforward as possible and cover the most basic scenarios needed for both the browse part and the transaction part of your shop:

    var rootCategories = catalogLibrary.GetRootCategories();
    
    

The APIs are simple abstractions on top of the actual platform implementation, which consists of a number of services such as those to calculate prices, find the right basket etc. Those are the dependencies that the APIs use to perform different operations.

Should you choose to modify the behavior of said dependencies, the API will still work seamless.

Context

To help you know what a customer is currently browsing in your store, context is exposed via context classes. You will know which store, catalog, category, and product the customer is currently browsing and also what the customer has added to her basket.

Available context classes are:

    
    var currentCategory = catalogLibrary.GetCategory();
    
    var categories = catalogLibrary.GetCategories(new List<Guid>() {currentCategory.Guid});
    
    

Summary

To make it easy to develop common features of online stores Ucommerce provides APIs in the form of libraries and context out of the box, which enables you to get the job done without hassle.

Should you need more control or different behavior from the APIs, you can override the default behavior in APIs and services to tailor the experience to whatever is required.