Personal Library

Kbid	Y29607
Last Modified	26-Jan-2021
Added to KB	03-Sep-2020
Public Access	Everyone
Status	Online
Doc Type	References
Product	ICM 7.10

Reference - Recommendation API 1.0.0

https://support.intershop.com/kb/Y29607

Share this document

Product Version	7.10
Product To Version
Status	final

Download Specification

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

icm-b2b-recommendation-1x0x0.yaml

API Specification

Introduction

OpenAPI Version: 3.0.1

Recommendation Version: 1.0.0

This is Intershop ICM REST API documentation.

This reference lists the REST API for storefront development. The REST API covers features of both, the B2C (SMB - Small and Medium-sized businesses) and the B2B storefront development.
This reference is intended for developers who want to make use of an easy-to-use API when developing frontend solutions.
You can find more information at Intershop Communications. Contact our Intershop experts at Support - Intershop Communications

Introduction

This API is documented in OpenAPI format.

Recommendation API

/recommendationcontexts

POST: Creates a new Recommendation Context

Description

The call is not mandatory - any other alpha-numeric string can be used instead

Java Method

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

Request Body

Request Parameters

Response

201 - Created

ResourceCollectionRO application/json

401 - Unauthorized

Recommendation Event API

/recommendationcontexts/{RecommendationContextKey}/events

POST: Sends an event to the recommendation engine

Description

If a recommendation service is configured this sends one of the following events to the recommendation engine:

ProductViewRecommendationEvent - The product with given ID [SKU] that has been viewed.
BasketRecommendationEvent - The items that have been added to the basket.
OrderRecommendationEvent - The items that have been ordered or the order with the given order number which were submitted.
SearchRecommendationEvent - A search with given search term has been processed
UserToSessionRecommendationEvent - Connects the current recommendation context with the given userid (after login). This event may affect the results of the recommendation requests.

The event can only be dispatched successfully if the installed Recommendation Engines support the event type and if the corresponding back office preference in 'Channel preferences / Recommendation Engines' is activated for the given event type. The used can be any alpha-numeric string. It will be used to distinguish between different users/customers.

Java Method

public javax.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	Description
in path	RecommendationContextKey	string	Required \| The key or UUID to resolve a single item \| Example: `ExampleKey`

Response

204 - No Content

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

Recommendation Request API

/recommendationcontexts/{RecommendationContextKey}/basketrecommendations

GET: Get recommended Products for the basket with the given basketID

Description

If a recommendation service is configured, this call returns a list of recommended products for the given basket. The resulting list strongly depends on the configuration of the recommendation engine and on the back office preferences in 'Channel preferences / Recommendation Engines'. If the request type BasketRecommendationRequest is not activated then an empty list is returned. The used can be any alpha-numeric string. It will be used to distinguish between different users/customers.

Java Method

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

Request Body

Request Parameters

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

Response

200 - OK

Object application/json

400 - Bad Request

401 - Unauthorized

404 - Not Found

/recommendationcontexts/{RecommendationContextKey}/productrecommendations

GET: Get recommended products for the given produkt(sku)

Description

If a recommendation service is configured this call returns a list of recommended products for the given product ID (SKU). The result list strongly depends on the configuration of the recommendation engine and on the back office preferences in 'Channel preferences / Recommendation Engines'. If the request type ProductRecommendationRequest is not activated then an empty list is returned.The used can be any alpha-numeric string. It will be used to distinguish between different users/customers.

Java Method

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

Request Body

Request Parameters

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

Response

200 - OK

Object application/json

400 - Bad Request

(when missing query parameter)

401 - Unauthorized

/recommendationcontexts/{RecommendationContextKey}/searchrecommendations

GET: Get recommended products for the given search term

Description

If a recommendation service is configured this call returns a list of recommended products for the given search term. The result list strongly depends on the configuration of the recommendation engine and on the back office preferences in 'Channel preferences / Recommendation Engines'. If the request type SearchRecommendationRequest is not activated then an empty list is returned. The used can be any alpha-numeric string. It will be used to distinguish between different users/customers.

Java Method

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

Request Body

Request Parameters

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

Response

200 - OK

Object application/json

400 - Bad Request

(when missing query parameter searchTerm)

401 - Unauthorized

/recommendationcontexts/{RecommendationContextKey}/topsellerrecommendations

GET: Get recommended global topseller products

Description

If a recommendation service is configured this call returns a list of recommended global top-seller products. The result list strongly depends on the configuration of the recommendation engine and on the back office preferences in 'Channel preferences / Recommendation Engines'. If the request type TopsellerRecommendationRequest is not activated then an empty list is returned. The used can be any alpha-numeric string. It will be used to distinguish between different users/customers.

Java Method

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

Request Body

Request Parameters

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

Response

200 - OK

Object application/json

401 - Unauthorized

/recommendationcontexts/{RecommendationContextKey}/userrecommendations

GET: Get recommended products for the assigned user

Description

If a recommendation service is configured this call returns a list of recommended products for the assigned user. The assignment of an user to the context-ID has to be done before with a separate REST Call (see UserToSessionRecommendationEvent at REST API - Recommendation events). The result list strongly depends on the configuration of the recommendation engine and on the back office preferences in 'Channel preferences / Recommendation Engines'. If the request type UserRecommendationRequest is not activated then an empty list is returned. The used can be any alpha-numeric string. It will be used to distinguish between different users/customers.

Java Method

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

Request Body

Request Parameters

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

Response

200 - OK

Object application/json

401 - Unauthorized

Request and Response Object Schemata

RecommendationEventRO application/json

{

"name":
string
The name of an element.
"type":
string
Readonly | The type of the object. This is normally a constant that can be used to differentiate objects 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 object. This is normally a constant that can be used to differentiate objects by their type.
}
]
"type":
string
The type of the object. This is normally a constant that can be used to differentiate objects by their type.
"sortKeys":
array
An array of string literals. The keys to sort for
"name":
string
The name of an element.

}

Object application/json

{

"links":
array
An array of object literals.
[
{
- "uri":
  string
  Format: uri
- "title":
  string
- "uriBuilder":
  object
- "rel":
  string
- "rels":
  array
  An array of string literals.
- "params":
  object
- "type":
  string
}
]
"statusInfo":
object
{
- "reasonPhrase":
  string
- "statusCode":
  integer
  Format: int32
- "family":
  string
  Possible Values: INFORMATIONALSUCCESSFULREDIRECTIONCLIENT_ERRORSERVER_ERROROTHER
}
"allowedMethods":
array
An array of string literals.
"stringHeaders":
object
{
- "empty":
  boolean
}
"mediaType":
object
{
- "type":
  string
- "subtype":
  string
- "parameters":
  object
- "wildcardType":
  boolean
- "wildcardSubtype":
  boolean
}
"entityTag":
object
{
- "value":
  string
- "weak":
  boolean
}
"metadata":
object
{
- "empty":
  boolean
}
"entity":
object
"lastModified":
string
Format: date-time
"date":
string
Format: date-time
"headers":
object
{
- "empty":
  boolean
}
"cookies":
object
"status":
integer
Format: int32
"length":
integer
Format: int32
"language":
object
{
- "language":
  string
- "script":
  string
- "country":
  string
- "variant":
  string
- "extensionKeys":
  array
  An array of string literals.
- "unicodeLocaleAttributes":
  array
  An array of string literals.
- "unicodeLocaleKeys":
  array
  An array of string literals.
- "iso3Language":
  string
- "iso3Country":
  string
- "displayLanguage":
  string
- "displayScript":
  string
- "displayCountry":
  string
- "displayVariant":
  string
- "displayName":
  string
}
"location":
string
Format: uri

}

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.