Naveed

The API Explorer and Event Builder from Sitecore Discover‘s CEC portal are excellent resources for developers, allowing them to formulate and execute Sitecore Discovers REST API requests against their data. After crafting a request in API Explorer or Event Builder, you are presented with two choices to copy it to your clipboard:

Copy as cURL using Sitecore host
Copy as data object

Sitecore Discover – API Explorer (click to enlarge)

If you have a subdomain configured, you get the third option to copy as cURL using your subdomain.

In the API Explorer, you can build and test a search and recommendation request as outlined in the official documentation.

Assuming you have successfully built an API request for search and recommendations API if you select the first option to copy as cURL using Sitecore host and paste it into a notepad, you will get output that looks something like this:

curl 'https://discover.sitecorecloud.io/search-rec/YOUR-CUSTOMER-KEY/3' -H 'accept-encoding: gzip, deflate, br' -H 'content-type: application/json' -H 'authorization: CUSTOMER-SEARCH-REC-API-KEY' -H 'accept: application/json' --data-binary $'{"data":{"context":{"page":{"uri":"/"},"user":{"uuid":"123456"}},"widget":{"rfkid":"rfkid_2"},"content":{"product":{}}}}' --compressed

And if you select the second option, copy as data object, and paste it into a notepad, you will get output that looks something like this:

{
  "context": {
    "page": {
      "uri": "/"
    },
    "user": {
      "uuid": "123456"
    }
  },
  "widget": {
    "rfkid": "rfkid_2"
  },
  "content": {
    "product": {}
  }
}

While we can build and test Sitecore Discover’s REST API calls via the API Explorer, what if we would like to evaluate them separately without its API Explorer environment? I prefer the Postman API Client for independent evaluation of REST API calls as it is easy to use and takes minimal effort to get started. When using the ‘copy as cURL with Sitecore host‘ option, I can easily import the cURL object I previously copied by selecting the ‘Import’ button in the Postman API client and then pasting the command (Ctrl+V) into the bar:

Once successfully imported into the Postman API client, I can operate the request and response object independently from the Sitecore Discover portal: (request & response are obscured in the screenshot below)

This is fantastic! In just a few clicks, I managed to create a request through the CEC portal against my data and verified it via Postman. As I started working with more Sitecore Discover REST API calls, it became clear that a Postman Collection for these API calls would be invaluable!

My Postman Collection

In my research, I found no Postman collection tailored for Sitecore Discover. Recognizing this need for myself and other fellow developers, I decided to develop one and share it with the community. I recommend all Sitecore community developers download this collection from my GitHub repository when they start working on their Sitecore Discover project, which will speed up their integration process.

My postman collection contains two JSON files in the GitHub repository:

The environment file.
The collection file.

Environment File

In the environment file, there are some settings you only need to update once like “customer_key” or “search_api_key“. However, you must update variables like the “access_token_search_rec” daily. Since the token lasts about a day, you can use the API calls for the whole day without interruption after you’ve authenticated and saved it. Check out the brief video gif below for a guide on importing the files after downloading:

Importing collection into Postman API client (click to enlarge)

The environment file has the following fields:

Variable Name	Type	Comments	Example
customer_key	string	The customer key is as per the CEC portal. Copy the value from the CEC portal.	11111-222333444
search_api_key	string	Search API Key. You may have one key for all or a separate key for each API end point. Copy the value from the CEC portal.	01-9c61b…09bc
event_api_key	string	Event API Key. You may have one key for all or a separate key for each API end point. Copy the value from the CEC portal.	01-9c61b…09bc
feed_api_key	string	Feed API Key. You may have one key for all or a separate key for each API end point. Copy the value from the CEC portal.	01-9c61b…09bc
services_api_key	string	Services API Key. You may have one key for all or a separate key for each API end point. Copy the value from the CEC portal.	01-9c61b…09bc
server_api_host	string	Server API host, as mentioned in your CEC portal. Copy the value from the CEC portal.	https://api.domain.com
scope_search	string	Pre-defined value for scope, do not change this value.	search-rec
scope_event	string	Pre-defined value for scope, do not change this value.	event
scope_feed	string	Pre-defined value for scope, do not change this value.	feed
scope_services	string	Pre-defined value for scope, do not change this value.	services
access_token_search_rec	string	The user-generated access token value for Search API. Copy the value after generating the token via Postman.	eyJ0e…gqag
access_token_feed	string	The user-generated access token value for Feed API. Copy the value after generating the token via Postman.	eyJ0e…gqag
access_token_events	string	The user-generated access token value for Event API. Copy the value after generating the token via Postman.	eyJ0e…gqag
access_token_services	string	The user-generated access token value for Services API. Copy the value after generating the token via Postman.	eyJ0e…gqag
refresh_token_search_rec	string	The user-generated refresh token value for Search API. Copy the value after generating the token via Postman.	eyJ0e…gqag
refresh_token_feed	string	The user-generated refresh token value for Feed API. Copy the value after generating the token via Postman.	eyJ0e…gqag
refresh_token_events	string	The user-generated refresh token value for Events API. Copy the value after generating the token via Postman.	eyJ0e…gqag
refresh_token_services	string	The user-generated refresh token value for Services API. Copy the value after generating the token via Postman.	eyJ0e…gqag
access_token_expiry	string	Length of token expiry in milliseconds. Default to 86400000 (a day).	86400000
refresh_token_expiry	string	Lenght of refresh token in milliseconds. Default to 604800000 (a week)	604800000

You’ll need to copy the “customer_key” and the “API keys” from the CEC portal into the environment file once. After generating a token, place it in the appropriate API token field, and then you can use the API for that specific section

Postman API client – The environment file

Collection File

The postman collection file is divided into four top level sections:

Authentication
Search & Recommendations
Events
Incremental Feed

Postman API Client – The collection file

Authentication Section

The Authentication section is further divided into four top level section:

Search & Recommendations
Events
Feed
Services

The concept is straightforward for this section: when working with search and recommendation APIs, use the token produced by the Authentication API and save it under the “access_token_search_rec” in the environment file. For the Events sections, save the token under the “access_token_events” variable, and so forth. What distinguishes these API calls is the unique “scope” variable in each POST and PUT request.

Postman API Client – Authentication Section

Search & Recommendations Section (API Explorer)

The Search & Recommendation section is divided into two top level sections:

Pages
Widgets

The “Pages” section caters to the primary Search API call and the Preview Search API call. On the other hand, the “Widgets” section is tailored for producing responses for individual widget components.

Postman API Client – Search & Recommendation section

Your implementation might include numerous widgets, but to get you started, I’ve provided a few standard widgets for the “Home Page” and “Product Details Page”. For any extra widget, just duplicate one of the API calls and modify the “body” according to the API explorer data object:

Steps to utilize Search & Recommendation API collection:

Generate a token using the corresponding Authentication API call and store it in the environmental variable.
Click on ‘Send‘ via the Postman API client.
If the request doesn’t match your requirements, navigate to CEC and update the request object using the options on the left. (see below)
Click ‘copy as data object‘ and replace everything that is inside the { “data” : { } } object. (see below)

API Explorer of the CEC portal – Create a custom search request.

Events Section (Events Builder)

The Events section is further divided into two top level sections:

Funnel Events (Non-Widgets)
Widget Events

Tracking events is an integral part of your implementation as it provides the data to the machine learning algorithms (Recipes) of Sitecore Discover. The ‘Event Builder‘ section in the CEC portal is used to build various request objects for tracking events. Once you have the tracking event, you must attach it to different “on click” or “page view” events.

The event API collection represents each event type, but many combinations exist for tracking events, and they will be unique per implementation. If your event isn’t present, you must return to the CEC portal and recreate the request object:

Event Builder of the CEC portal – create a custom event request

As you get familiar with the event API, you’ll see that only slight adjustments are typically needed for each event API call. Changes will predominantly involve the “rfkid,” “click_type,” or “click_text” attributes. This collection is intended to serve as an initial foundation, recognizing that every implementation can differ considerably from another.

Incremental Feed Section

In one of my previous blogs, I provided step-by-step guidance on enabling an incremental feed for Sitecore Discover and resolving any issues. To work with this API, ensure you have the correct token specified in the environmental file for “access_token_feed” variable, and the CEC can accept incremental feed data.

TLDR;

My Postman API collection enhances your development process and works seamlessly with Sitecore Discover’s REST APIs. It streamlines integration with Sitecore Discover aiming for a faster and smoother development workflow.

Thanks