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

A UUID v4 should contain dashes, e.g., f2a9fd61-ca3d-41be-baec-c47b171bc51a. Both upper and lower case are supported, but be consistent with the chosen format throughout the implementation.

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 Elevate to understand that they refer to the same visitor, or they can be migrated explicitly using Customer keys migration.

RESTful API¶

Base URL¶

The base URL for the Voyado Elevate 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 Elevate 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.
Elevate 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 Elevate entity attributes is now an array. Attributes defined in Elevate 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, with the exception of when using limit on a panel, then empty panels are removed.

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.
Voyado Elevate 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).