Ecommerce Search Developer Overview

In this article we will look at Ecommerce Search from a developers perspective and provide you with the overview and references you need to get started.

Before getting started

In this concept article you can find an overview of Ecommerce Search, delving into its fundamental concepts and detailing its key features. If you haven't already, we highly recommend reading it to ensure you're well-equipped with the foundational knowledge needed to make the most out of this article.

You should also review our versioning strategy to understand how we manage releases. Additionally, you may find it helpful to read about our approach to software development at Bizzkit.

API overview

In the heart of Ecommerce Search lie three distinct APIs: Admin, Search, and Courier. Each API serves a unique purpose, forming an interconnected system that delivers robust functionality.

Admin API

The Admin API is for managing various aspects of Ecommerce Search. From curating dictionaries and parameters to handling products and SKUs, the Admin API provides you with the tools you need to configure and maintain your search system, ensuring that it aligns perfectly with your specific needs and the needs of your customers.

Click here for the Admin API Swagger reference

Search API

The Search APIs primary role is to provide powerful search capabilities, offering suggestions and 'did-you-mean' features to enhance the user experience. A key recommendation for developers is to leverage the unified endpoint, a streamlined interface that allows you to access and manage all available search features effectively. Unique among all the APIs, the Search API also is accessible directly through a frontend client.

Click here for the Search API Swagger reference

Courier API

The Courier API is offering a way for incorporating data from Bizzkit applications like the CMS, third-party sources like Google Analytics and Raptor Services into Ecommerce Search. By using the Courier API, developers can enhance the depth and breadth of their search data, enriching the user experience and providing more personalized, relevant search results.

Click here for the Courier API Swagger reference

Using the admin API

Given a valid authentication token here is an example of calling the segments-endpoint:

1
2

curl -X GET https://myenv-ecs.bizzkit.biz/api/segments `
-H "Authorization: Bearer ..." `

1
2
3
4
5

# authtoken defined and initialized previously
@api = https://myenv-ecs.bizzkit.biz

GET {{api}}/api/segments HTTP/1.1
Authorization: Bearer {{authtoken}} 

Using the Bizzkit .NET admin SDK

For easy integration with Microsoft .NET, Bizzkit offers SDK packages. These packages include auto-generated Swagger clients and a factory class to simplify authentication. They automate token renewal and provide type-safe methods for the API endpoints.

All SDK package names start with the prefix Bizzkit.Sdk., and the SDK packages incorporate the following elements:

• A client factory
• A dedicated client
• Options to configure the client factory

To access the Bizzkit NuGet packages in your preferred development environment, you need to reference the Bizzkit Partner feed. You can, for example, do this by adding a nuget.config file to your project with the following configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="nuget" value="https://api.nuget.org/v3/index.json" />
    <add key="bizzkit-partner" value="https://pkgs.dev.azure.com/bizzkit-platform/7dad82b4-f2ae-4a3a-ab87-3fc791e4ea62/_packaging/bizzkit-partner-feed/nuget/v3/index.json" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="nuget">
      <package pattern="*" />
    </packageSource>
    <packageSource key="bizzkit-partner">
      <package pattern="Bizzkit*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

This configuration clears existing package sources and adds the Bizzkit Partner feed alongside the official NuGet source.

Once the feed is configured, you can install the required NuGet package using the following command:

1

dotnet add package Bizzkit.Sdk.EcommerceSearch

To simplify the authentication process, all NuGet packages associated with Bizzkit applications come with a factory class. This class streamlines the creation of an authenticated Swagger-generated client.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

using Bizzkit.Sdk.EcommerceSearch;

var factory = new SearchAdministrationClientFactory(new SearchAdministrationConnectionOptions
{
    BaseUrl = "https://myenv-ecs.bizzkit.biz",
    Authority = "https://myenv-auth.bizzkit.biz",
    ClientId = "BizzkitClient",
    ClientSecret = "BizzkitSecret",
    Scope = "searchapi/"
});

var client = await factory.CreateAuthenticatedClientAsync();

As noted earlier, the SDK client is mainly an auto-generated client based on the OpenAPI interface, meaning all methods map directly to the API.

Below is an example of calling the Segments endpoint using the SDK client (with the factory and client already created):

1
2

var test = await client.ListSegmentsAsync();
test.ToList().ForEach(s => Console.WriteLine(s.Name));

Using the search API

The Search API is public, so unless you need to perform an authenticated search to handle different price groups or retrieve protected attributes, it can be used without an authentication token. Below is a simple example of calling the UnifiedSearch endpoint:

1
2
3

curl -X POST https://myenv-ecs-search.bizzkit.biz/search `
-H 'Content-Type: application/json' `
-d '{ "segmentId": "merch-b2c-en",  "scopeId": "browse",  "phase": "red" }' 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

@api = https://myenv-ecs-search.bizzkit.biz
@segmentId = merch-b2c-en 
@scope = browse

POST {{api}}/search HTTP/1.1
Content-Type: application/json

{
    "segmentId": "{{segmentId}}",
    "scopeId": "{{scope}}",
    "phrase": "red"        
}

Using the Bizzkit TypeScript client

For developers working with JavaScript-based applications, we offer an auto-generated TypeScript client specifically tailored for the Search API. This allows you to harness the powerful features of our Search API directly within your TypeScript applications, reducing the need for manual API calls and enhancing your development efficiency.

To access the Bizzkit NPM package in your preferred development environment, you need to reference the NPM feed. You can, for example, do this by adding a .npmrc file to your project with the following configuration:

1
2
3

registry=https://registry.npmjs.org
save-exact=true
@bizzkit:registry=https://pkgs.dev.azure.com/bizzkit-platform/7dad82b4-f2ae-4a3a-ab87-3fc791e4ea62/_packaging/bizzkit-partner-feed/npm/registry/

Once the feed is configured, you can install the required package using the following command:

1

npm install @bizzkit/ecommerce-search

Below is a simple TypeScript example of calling the search-endpoint using the client:

1
2
3
4
5
6
7
8
9

import { Client } from '@bizzkit/ecommerce-search/client';

const searchClient = new Client({ baseUrl: "https://myenv-ecs-search.bizzkit.biz" });
const response = await searchClient.search.search(
{
    segmentId: "merch-b2c-en",
    scopeId: "browse",
    phrase: "red"
});

Job runners

Complementing these APIs are two job runners powered by Hangfire. In Ecommerce Search, Hangfire is leveraged to manage tasks for both the Ecommerce Search Admin API and the Courier API, ensuring that your system runs smoothly and efficiently, even when handling complex tasks or dealing with large volumes of data.

Setting up

To get started with an Ecommerce Search installation you need to create segments, scopes, parameters, etc. In the menu you can find links to:

• Getting started with a complete guide to get you started
• Segments
• Scopes
• Contexts
• Dashboards
• Publications
• Targets

Ingesting data

When you ingest data to Ecommerce Search you need information about products, SKUs, etc:

• Products
• Content
• Ingestion

Searching

When searching you need information about text analysis, sorting, etc:

• Searching
• Authenticated search
• Text analysis
• Suggestions
• Commercial sorting
• Diagnostics

Other resources

We highly recommend that you also take a close look at Tutorials section for practical guides and further insights.