Install SDK

8 min

📘 Note This package contains all of the endpoints provided by Optimizely Commerce API. A comprehensive list of services can be found in the swagger API documentation here.

Install the SDK

The API software development kit (SDK) is delivered as a Nuget package that can be imported by adding the Optimizely.Commerce.API to your projects.

Before using the API SDK, you need to complete a few steps:

Configure the project.

Implement additional services.

Inject the API Service provider into your class.

Configure the project.

The API SDK needs to know the host URL, client secret, and client ID of your Configured Commerce instance before communicating with the Configured Commerce API. You also need to enable/disable caching with the package configuration.

You can configure the package in several ways. Optimizely provides an IServiceCollection extension that registers all needed services and configures the project for you. You can also override our ClientService class's CreateClient() manually with your custom code.

IServiceCollection extension

The IServiceCollection extension method registers all necessary services to your IoC Container and assigns the host, client id and client secret. It can also toggle caching on or off. To configure the SDK this way, call the provided ServiceCollectionExtension's extension method, AddComerceSdk(string Host, string ClientID, string ClientSecret, bool IsCachingEnabled).

yourServiceCollection.AddCommerceSdk("yourHost.url", "yourClientID", "yourClientSecret",  enableCaching)

Substitute the following variables with the appropriate values for your context:

host – The domain URL.

clientID – Your ID

clientSecret – Your Access Token

isCachingEnabled – A Boolean used to determine if the SDK should load a cached version if the service returns an empty response.

You also need to register the services you implement (required services) to your IoC Container:

yourServiceCollection.AddSingleton<ICommerceAPIServiceProvider, YourAPIServiceProviderImp();
yourServiceCollection.AddSingleton<ILocalStorageService, YourLocalStorageImp>();
yourServiceCollection.AddSingleton<ISecureStorageService, YourSecureStorageImp>();
yourServiceCollection.AddSingleton<INetworkService, YourNetworkServiceImp>();
yourServiceCollection.AddSingleton<ITrackingService, YourTrackingServiceImp>();

Manual configuration

If you use something other than the IServiceCollection to help with dependency injection, you can manually register the services to whichever container you use. Below is a list of the services and their respective implementation classes that need to be registered.

ICommerceAPIServiceProvider, CommerceAPIServiceProvider>();
IMessengerService, MessengerService>();
ICartService, CartService>();
ILoggerService, Logger>();
IClientService, OptClientService>();
IAdminClientService, AdminClientService>();
Locator.Current.GetService<IFilesystemProvider>());
heService, CacheService>();
ISessionService, SessionService>();
ICategoryService, CategoryService>();
IAccountService, AccountService>();
IAuthenticationService, AuthenticationService>();
IAdminAuthenticationService, AdminAuthenticationService>();
ISettingsService, SettingsService>();
IProductService, ProductService>();
IProductV2Service, ProductV2Service>();
IWebsiteService, WebsiteService>();
IWarehouseService, WarehouseService>();
ILocatorService, LocatorService>();
IBillToService, BillToService>();
IOrderService, OrderService>();
IWishListService, WishListService>();
IMessageService, MessageService>();
IMobileContentService, MobileContentService>();
IMobileSpireContentService, MobileSpireContentService>();
IAutocompleteService, AutocompleteService>();
IBrandService, BrandService>();
ITranslationService, TranslationService>();
IDealerService, DealerService>();
IInvoiceService, InvoiceService>();
IJobQuoteService, JobQuoteService>();
IQuoteService, QuoteService>();
IVmiLocationsService, VmiLocationsService>();

When manually configuring the project to your environment, you should overwrite our ClientService.CreateClient() method. You will need to assign the host, clientId and clientSecret and set the IsCachingEnabled Boolean value. You can also configure the HTTP client. An example implementation might look something like the following:

    public class CommerceClientService : ClientService
    {
        public CommerceClientService(ICommerceAPIServiceProvider commerceAPIServiceProvider)
            : base(commerceAPIServiceProvider)
        {
        }

        public void CreateClient()
        {
            this.Host = "yourHostURL";
            this.ClientId = "yourID";
            this.ClientSecret = "yourSecret";
            ClientConfig.IsCachingEnabled = true;

            base.httpClientHandler = new HttpClientHandler
            {
                AllowAutoRedirect = true,
                UseCookies = true,
                CookieContainer = new CookieContainer(),
                ClientCertificateOptions = ClientCertificateOption.Automatic,
            };

            this.client = new HttpClient(new RefreshTokenHandler(base.httpClientHandler, this.RenewAuthenticationTokens, this._commerceAPIServiceProvider.GetLoggerService(), this.NotifyRefreshTokenExpired))
            {
                Timeout = Timeout.InfiniteTimeSpan,
            };
        }
    }

If you are not using the IServiceCollection extension method, you can call our static ClientConfig class's InitClientConfig(string hostURL, string clientId, string clientSecret, bool isCachingEnabled) within your start-up class before you register the services to your IoC Container.

ClientConfig.InitClientConfig("hostURL", "clientId", "clientSecret", isCachingEnabled)

If caching is enabled

If you have enabled caching, you need to add Akavache to your project and grab an instance of Akavache's IFilesystemProvider interface, preferably using Splat's Locator class.

If using IServiceCollection: services.AddSingleton(Locator.Current.GetService<IFilesystemProvider>());

Implement Additional Services

Once the package has been configured using either approach, you need to implement platform-specific services in order for the SDK to function properly. The interfaces to do this are provided by the API SDK package but must be implemented by you. These include the following:

ILocalStorageService

ISecureStorageService

INetworkService

ITrackingService

ICommerceAPIServiceProvider

You can view more information in the SDK Reference Guide.

Use the SDK

Once you have configured the API SDK, you can make calls to the Configured Commerce API. To reduce the number of services you need to inject on your own, you should use the ICommerceAPIServiceProvider implementation you created in Step 2. Inject this into your class and call the appropriate getter method.

public YourClass(ICommerceAPIServiceProvider commerceAPIServiceProvider)
{
    public void DoSomething()
    {
        var result = await commerceAPIServiceProvider.GetAccountService().GetAccountsAsync();
        // Handle result
    }
}

Some service methods require you to provide values for the query parameters. QueryParameter objects can assist you in this area.

var parameters = new BillTosQueryParameters
    {
        Filter = this.CurrentSearchText,
        Page = this.currentPage,
        Exclude = new List<string> { "excludeshowall" },
    };

var billToResult = await commerceAPIServiceProvider.GetBillToService().GetBillTosAsync(parameters);