Skip to content

Upgrading to Web API v2

Since the Web API v2 is not backward compatible some actions are required when migrating from v1 to v2. This section is meant as a guide for the migration and it summarizes the major breaking changes introduced in v2.

Session properties

  • sessionKey: Must now be a valid UUID v4
  • customerKey: Must now be a valid UUID v4
  • token: Removed
  • market: Must be a configured market to be allowed in notifications

Signed in visitors

In v1 the customerKey was set to a SHA256 calculated via the CustomerKeyAuthentication class. This has been removed and is now always a UUID v4. The UUID should be stored by the retailer for each visitor.

The old customerKey and the new one should be used together in the same session at least once for eSales to understand they refers to the same visitor.

RESTful API

Base URL

The base URL for the Apptus eSales Web API v2 is now https://{cluster-id}.api.esales.apptus.cloud.

Authentication

Two different security mechanisms needed to be implemented when using the Web API v1: security tokens and basic authentication. Different resources needed different security mechanisms.

Web API v2 provides a unified way to handle resources requiring additional security via a new customer header, the Api-Key header. The value of this header is the customer's {PRIVATE-KEY}.

The affected endpoints are the following:

Notifications

A stricter validation of notifications has been introduced. Many validation warnings are now considered as errors instead. For instance, using a non matching product key and variant key in a notification will now fail.

Query parameters

In Web API v2 the namespace esales. is used for session parameters (i.e. market, session key and customer key) and other parameters do not need to be prepended with args. anymore. So when migrating panel requests from v1:

  • esales.sessionKey, esales.customerKey, and esales.market should be in the query string instead of sessionKey, customerKey, and market
  • arg. should be removed from all other parameters.

As for notifications, a stricter validation of query parameters has been introduced. The query parameters esales.sessionKey, esales.customerKey, and esales.market are now mandatory.

New endpoints

A new endpoint for exports is introduced. The export endpoint allows for exporting of a customer's eSales configuration, products, panels, and more.

Dynamic pages

Two major changes have been introduced when working with dynamic pages.

  • All query parameters except esales.sessionKey, esales.customerKey, and esales.market have been moved into the body.
  • All dynamic page tokens have been removed from v2 in favor of the Api-Key header in the HTTP request.

The second change has a larger impact on the integration. In Web API v1 each panel in a dynamic page needed to have a valid dynamic page token. These security tokens were necessary to limit possible misuse when working with dynamic pages client-side. Token generation needed to be done beforehand on server-side as an extra integration step.

The usage of the customer's private key in the request header makes working with dynamic pages much simpler, but forces the integration to be server-side.

Query result

The query result format has been modified in v2. The major changes are:

  • Unnecessary and debug information has been removed making the result more compact and avoiding unnecessary data transfer.
  • eSales entity attributes such as product_key, variant_key, and ad_key have been moved from attributes to specific properties of the entities.
  • Each attribute in eSales entity attributes is now an array. Attributes defined in eSales as comma-separated or pipe-separated lists of values are now automatically parsed and returned as lists of values.
  • Empty panels and panels containing errors are now returned as well making the result more predictable.

Furthermore v2 returns more consistent HTTP status codes for responses where one or more sub-panels contain errors, e.g. if a sub-panel fails because of a wrong argument, the status code will be 400 and not 200 as with Web API v1.

Import and exports for synonyms

A new format for import and export of synonyms is introduced.

<?xml version='1.0' encoding='UTF-8'?>
<operations>
    <clear>
        <synonym/>
    </clear>
    <add>
        <synonym>
            <locale>en-GB</locale>
            <search_phrase>Shoes</search_phrase>
            <synonym_phrase>Boots</synonym_phrase>
        </synonym>
    </add>
</operations>

If a visitor searches for Shoes, it will also include searches for Boots in the result.

JavaScript library

A new JavaScript library is used for Web API v2. Always use the latest version. It is not backwards compatible with the Web API v1.

  • The JavaScript library now uses Promises instead of Callbacks for HTTP requests.
  • Apptus cookies (customerKey and sessionKey) are automatically validated in the JavaScript library. Valid cookies are UUID v4 and invalid cookies will not be accepted.
  • Dynamic pages can no longer be called client-side. If dynamic pages are used they must be called server-side or be converted into zones.
  • The library has a more structured implementation which results in slightly different integration details. For instance the implementation of non-eSales notifications now takes an object as input instead of two strings (i.e. product key and variant key).
×