Reference - Recommendation REST API 1.1.0

Document View

This API specification is available for download as an Open API 3.0 YAML file:

icm-b2b-recommendation-1x1x0.yaml

References

The following page lists available REST APIs for ICM 11 and their version dependencies:

Reference - Intershop Commerce Management 11 REST API

API Specification

Introduction

OpenAPI Version: 3.0.1

Recommendation Version: 1.1.0

The Recommendation REST API contains operations that allow to improve the online shopping experience by offering personalized product suggestions to customers. Recommendations are based on user behavior and product relationships, and they can be used in various contexts within your online shop. Using this REST API requires a configured recommendation engine.

For more details, see Overview - Recommendation in the Intershop Knowledge Base.

Changelog

Version 1.1.0

Added this changelog
Corrected wrong status codes
Minor documentation changes (recommendationcontexts, events)

Recommendation API

/recommendationcontexts

POST: Creates a new recommendation context

Description

This operation creates a new recommendation context. A recommendation context is just a simple string that is used as a replacement for the session ID. All events that are created for a recommendation context via REST are tagged with this context ID when they are transmitted to the connected recommendation engine. It has no semantic meaning to the recommendation engine, it just symbolizes that events with the same ID belong to the same session. This is necessary to ensure a valid data basis.

Java Method

public jakarta.ws.rs.core.Response com.intershop.component.recommendation.capi.rest.resource.RecommendationContextListResource.createContext()

Request Body

Request Parameters

Response

201 - Created

LinkRO */*

Recommendation Event API

/recommendationcontexts/{RecommendationContextKey}/events

POST: Creates a new recommendation context

Description

This operation creates a new recommendation context. This requires a configured recommendation service. To use this operation, specify one of the following events in the request body:

ProductViewRecommendationEvent - The product with the given productID [SKU] that has been viewed.
BasketRecommendationEvent - The items that have been added to the basket.
OrderRecommendationEvent - The items that were ordered or the order with the specified orderID that was submitted.
SearchRecommendationEvent - A search with the given searchTerm that has been processed.
UserRecommendationEvent - Connects the current recommendation context with the given userID. This event may affect the results of the recommendation requests.

The event can only be sent successfully if the installed recommendation engines support the event type and if the corresponding back office preferences of the channel (Preferences | Recommendation Engines) are enabled for the given event type.

All events which are sent to the recommendation engine will be tagged with the RecommendationContextKey to express that they belong to a specific session. See the description of "POST /recommendationcontexts".

Java Method

public jakarta.ws.rs.core.Response com.intershop.component.recommendation.capi.rest.resource.EventRecommendationsListResource.sendEvent(com.intershop.component.recommendation.capi.rest.resourceobject.RecommendationEventRO)

Request Body

RecommendationEventRO application/json

Request Parameters

Location	Name	Format	Default	Example	Description
in path	RecommendationContextKey	string		`ExampleKey`	Required \| The key or UUID to resolve a single item

Response

204 - No Content

400 - Bad Request - Unknown event type

404 - Not Found

Recommendation Request API

/recommendationcontexts/{RecommendationContextKey}/basketrecommendations

GET: Returns recommended products for the given basket

Description

This operation returns a list of recommended products for the given basket based on the basketID. This requires a configured recommendation service. The resulting list strongly depends on the configuration of the recommendation engine and on the back office preferences of the channel (Preferences | Recommendation Engines). If the request type BasketRecommendationRequest is not enabled, an empty list is returned.

Java Method

public jakarta.ws.rs.core.Response com.intershop.component.recommendation.capi.rest.resource.BasketRequestRecommendationsListResource.getBasketRecommendations(java.lang.String)

Request Body

Request Parameters

Location	Name	Format	Default	Example	Description
in path	RecommendationContextKey	string		`ExampleKey`	Required \| The key or UUID to resolve a single item
in query	basketID	string		`56z8zttzCtzgtzAAAF1ut8DHYjo`	The UUID of the basket to get recommendations for

Response

200 - OK

ResourceCollectionRO application/json

400 - Bad Request - Missing parameter

404 - Not Found

/recommendationcontexts/{RecommendationContextKey}/productrecommendations

GET: Returns recommended products for the given product (SKU)

Description

This operation returns a list of recommended products for the given product ID (SKU). This requires a configured recommendation service. The result list strongly depends on the configuration of the recommendation engine and on the back office preferences of the channel (Preferences | Recommendation Engines). If the request type ProductRecommendationRequest is not enabled, an empty list is returned.

Java Method

public jakarta.ws.rs.core.Response com.intershop.component.recommendation.capi.rest.resource.ProductRequestRecommendationsListResource.getProductRecommendations(java.lang.String)

Request Body

Request Parameters

Location	Name	Format	Default	Example	Description
in path	RecommendationContextKey	string		`ExampleKey`	Required \| The key or UUID to resolve a single item
in query	productID	string		`124566`	The SKU of the product to get recommendations for

Response

200 - OK

ResourceCollectionRO application/json

400 - Bad Request - Missing parameter

/recommendationcontexts/{RecommendationContextKey}/searchrecommendations

GET: Returns recommended products for the given search term

Description

This operation returns a list of recommended products for the given search term. This requires a configured recommendation service. The result list strongly depends on the configuration of the recommendation engine and on the back office preferences of the channel (Preferences | Recommendation Engines). If the request type SearchRecommendationRequest is not enabled, an empty list is returned.

Java Method

public jakarta.ws.rs.core.Response com.intershop.component.recommendation.capi.rest.resource.SearchRequestRecommendationsListResource.getProductRecommendations(java.lang.String)

Request Body

Request Parameters

Location	Name	Format	Default	Example	Description
in path	RecommendationContextKey	string		`ExampleKey`	Required \| The key or UUID to resolve a single item
in query	searchTerm	string		`Acer`	The search term to get recommendations for

Response

200 - OK

ResourceCollectionRO application/json

400 - Bad Request - Missing parameter

/recommendationcontexts/{RecommendationContextKey}/topsellerrecommendations

GET: Returns recommended global top-selling products

Description

This operation returns a list of recommended global top-selling products. This requires a configured recommendation service. The result list strongly depends on the configuration of the recommendation engine and on the back office preferences of the channel (Preferences | Recommendation Engines). If the request type TopsellerRecommendationRequest is not enabled, an empty list is returned.

Java Method

public jakarta.ws.rs.core.Response com.intershop.component.recommendation.capi.rest.resource.TopsellerRequestRecommendationsListResource.getProductRecommendations()

Request Body

Request Parameters

Location	Name	Format	Default	Example	Description
in path	RecommendationContextKey	string		`ExampleKey`	Required \| The key or UUID to resolve a single item

Response

200 - OK

ResourceCollectionRO application/json

/recommendationcontexts/{RecommendationContextKey}/userrecommendations

GET: Returns recommended products for the assigned user / recommendation context

Description

This operation returns a list of recommended products for the assigned user. This requires a configured recommendation service. The assignment of a user to the recommendation context must be done separately (see description of POST /recommendationcontexts/{RecommendationContextKey}/events - UserRecommendationEvent). If no user is assigned to the recommendation context, the delivered recommendations are of a general nature and not user-specific. The result list strongly depends on the configuration of the recommendation engine and on the back office preferences of the channel (Peferences | Recommendation Engines). If the request type UserRecommendationRequest is not enabled, an empty list is returned.

Java Method

public jakarta.ws.rs.core.Response com.intershop.component.recommendation.capi.rest.resource.UserRequestRecommendationsListResource.getProductRecommendations()

Request Body

Request Parameters

Location	Name	Format	Default	Example	Description
in path	RecommendationContextKey	string		`ExampleKey`	Required \| The key or UUID to resolve a single item

Response

200 - OK

ResourceCollectionRO application/json

Request and Response Object Schemata

LinkRO */*

{

"name":
string
The name of the returned element
"type":
string
Readonly | This is a constant: Link | Example: Link
"attributes":
array
An array of ResourceAttribute objects. The list of attributes
[
ResourceAttribute: An attribute
{
- "name":
  string
  The attribute's name
- "type":
  string
  This is a constant: ResourceAttribute | Example: ResourceAttribute
- "value":
  object
  The attribute's value.
}
]
"uri":
string
The URI
"relation":
string
The relation of the link | Documentation: Link Relations (www.iana.org) | Possible Values: aboutalternateappendixarchivesauthorbookmarkcanonicalchaptercollectioncontentscopyrightcreate-formcurrentdescribedbydescribesdisclosureduplicateeditedit-formedit-mediaenclosurefirstglossaryhelphostshubiconindexitemlastlatest-versionlicenselrddmonitormonitor-groupnextnext-archivenofollownoreferrerpaymentpredecessor-versionprefetchprevpreviewpreviousprev-archiveprivacy-policyprofilerelatedrepliessearchsectionselfservicestartstylesheetsubsectionsuccessor-versiontagterms-of-servicetypeupversion-historyviaworking-copyworking-copy-of
"title":
string
The title of the link
"description":
string
The description of the link
"itemId":
string
The ID of the linked item
"attribute":
object
A ResourceAttribute object. An attribute
{
- "name":
  string
  The attribute's name
- "type":
  string
  This is a constant: ResourceAttribute | Example: ResourceAttribute
- "value":
  object
  The attribute's value.
}

}

RecommendationEventRO application/json

{

"name":
string
The name of an element
"type":
string
Readonly | The type of the element. This is normally a constant that can be used to differentiate elements by their type.

}

ResourceCollectionRO application/json

{

"pageable":
string
The pageable ID
"total":
integer
The pageable amount total | Format: int32
"offset":
integer
The pageable offset | Format: int32
"amount":
integer
The pageable amount | Format: int32
"elements":
array
An array of AbstractResourceObject objects. The list of elements
[
AbstractResourceObject: The list of elements
{
- "name":
  string
  The name of an element
- "type":
  string
  Readonly | The type of the element. This is normally a constant that can be used to differentiate elements by their type.
}
]
"type":
string
The type of the element. This is normally a constant that can be used to differentiate elements by their type.
"sortKeys":
array
An array of string literals. The keys to sort for
"name":
string
The name of an element

}

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.