API¶
The Voyado Elevate 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 Voyado Elevate Cluster and includes both automatic load balancing and fail over.
The API has three main integration areas: Imports to import products and content into Elevate, queries to retrieve results, and notifications to share visitor behavior with Elevate for reporting and behavior analysis.
A JavaScript library, including TypeScript models, is available to facilitate client side integrations to Voyado Elevate using the HTTP API.
Getting started¶
To get started with the Voyado Elevate API integration, a few prerequirements must be met.
- Origin host and cross-origin resource sharing available
- Cluster credentails received
- Connection requirements met
Once these have been met, read through Tips and best practices and continue with integrating queries and notifications using the Storefront API.
Origin host and cross-origin resource sharing¶
Cross-origin resource sharing (CORS) is a mechanism for controlling what domain Ajax requests to the cluster are allowed to originate from. Voyado can help with the origin host configuration as part of the customer onboarding process, if you provide the necessary information.
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)
Connection requirements¶
- TLS version 1.3 is recommended. Version 1.2 is supported.
- 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¶
Caching¶
A general rule of thumb is to never cache Elevate 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.
Request parameters¶
Query parameters are case sensitive.
Request headers¶
Compression¶
All responses that are applicable from Elevate will be compressed with gzip if the request header Accept-Encoding
has the value gzip
, i.e. the Voyado Elevate HTTP API supports gzip
encoded responses. For performance reasons, it is recommended to always use compressed responses.
User agents¶
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 application/json
as 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.
Utility resources¶
OpenAPI specification¶
Each version of each API contains a downloadable OpenAPI specification that can be tested using Swagger UI. The specifications are found on the overview page for the corresponding API version.
Postman collections¶
Each version of each API contains a downloadable postman collection that can be tested using the tool Postman. The collections are found on the overview page for the corresponding API version.
Setting environment variables¶
Note that the file uses environment variables, located under the Variables tab in the Postman interface (see image below). To run the requests, the cluster-id
variable must first be changed. The cluster-id
will automatically be applied to the baseUrl
parameter.