Reference - ICM REST API - B2C Front End - Recommendation 1.0.0


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: 

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

LocationNameFormatDescription
in pathRecommendationContextKeystringRequired | 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

LocationNameFormatDescription
in pathRecommendationContextKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey
in querybasketIDstring

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

LocationNameFormatDescription
in pathRecommendationContextKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey
in queryproductIDstring

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

LocationNameFormatDescription
in pathRecommendationContextKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey
in querysearchTermstring

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

LocationNameFormatDescription
in pathRecommendationContextKeystringRequired | 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

LocationNameFormatDescription
in pathRecommendationContextKeystringRequired | 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.

Customer Support
Knowledge Base
Product Resources
Tickets