The Apptus eSales 4 API enables server and client side integrations through HTTP queries that returns raw JSON data, enabling unlimited flexibility and customization. The API handles the communication with the Apptus eSales Cluster and includes both automatic load balancing and fail over.
The API has three main integration areas: Imports to import products and content into eSales, Queries to retrieve results, and Notifications to share visitor behavior with eSales for reporting and behavior analysis.
To get started with the eSales 4 API integration, a few prerequirements must be met.
- Origin host settings have been communicated
- Cluster credentails have been received
- Connection requirements are met
The origin host is part of the security settings for a cluster. It specifies what domain Ajax requests to the cluster are allowed to originate from. This setup is part of the customer onboarding process and performed by Apptus, with information provided by the retailer.
Default configuration allows Ajax requests originating from all origins but a restricted access to the API is recommended. The following information is needed from the customer to configure the origin host correctly:
- Protocols (HTTP/HTTPS)
- Domains (subdomains)
- Ports (80, 443)
- TLS version 1.2 or 1.3 are recommended. Versions 1.0 and 1.1 are deprecated and support will be phased out.
- Server Name Indication (SNI) enabled.
- A CA certificate store that trusts Let's Encrypt root certificates. For more information, see Let's Encrypt Certificate Compatibility.
- HTTP/2 is recommended. Version 1.1 is also supported.
Tips and best practices¶
A general rule of thumb is to never cache eSales generated responses. Caching prevents personalization and can cause notifications to be erroneous due to cached tickets. This does not include static data and resources such as images, which can be cached.
Query parameters are case sensitive.
All responses that are applicable from eSales will be compressed with gzip if the request header
Accept-Encoding has the value
gzip, i.e. the eSales 4 HTTP API supports
gzip encoded responses. For performance reasons, it is recommended to always use compressed responses.
For internal tracking, helpful for troubleshooting, as well as for potential future features, it is recommended to provide a User-Agent header in the requests to the HTTP API.
Browser preflight requests¶
To support large requests with unique page configurations, queries can be performed through HTTP
POST. Queries return JSON objects as responses, but requests in browsers with
content-type automatically triggers a preflight request. To avoid this,
text/plain is supported as
content-type and can be used in client side integrations.