Introduction to the Content API (CAPI)
The Content API (CAPI) is a service for our clients which enabling them to obtain resized images of specific SKUs. This can be used to create a synchronization service between the clients ecommerce platform and other digital platform and the Cylindo imagery.
Examples of usage for CAPI falls into two categories:
- High request scenarios e.g. where the images are embedded directly on a product listing page or used as thumb imagery on a cart page. This scenario is possible if the maximum resolution requested is equal to or smaller than the resolution of the agreed upon 360 viewport.
- Low requests scenarios e.g. where a local buffer is generated or where marketing material requires high resolution imagery. It is possible to obtain a product image in any resolution smaller than 4096 pixel using CAPI.
In version 3 of the Content API, access requests can be made in the following two ways.
Any requests for images that are smaller or equal to the size of your agreed upon 360 viewport can be made without any authentication. This means that once you have the URL of your images you can use the URL to retrieve images dynamically at runtime. These images are fronted by a CDN for faster access.
Any requests for images that are larger than your agreed upon viewport will require you to programmatically access the Content API and attach your access key in the image retrieval request as described below. You can obtain an access key by contacting email@example.com with a request for access.
Here is a summary of what is required to use CAPI:
- Knowledge of the SKU you want to retrieve and its parameters (size, frame etc.).
- Your access key - if the size that you are requesting is larger than your default viewer size then include your CAPI access key. You can obtain an access key by contacting firstname.lastname@example.org with a request for CAPI access.
It is best practice to create a switch in your ecommerce platform that can enable the Cylindo 360 HD Viewer on a per product basis. This can be used to quickly switch between the Cylindo 360 HD Viewer experience and a static image you host. If you do not have imagery to use as a static image then Cylindo can provide the images to you which you can use (e.g. the first frame of the viewers). Or you can use the CAPI to download the images programmatically. Examples for how you can retrieve images with CAPI are given in section 6 of this document.
It is however only possible to do so if using a technology that allows for dynamic server side content such as e.g. php, aspx, etc. The size requested from CAPI determines what is needed to request an CAPI image. If you select a size that is larger than your standard 360 image resolution then you need to add an authorization header (request your authorization details from email@example.com). When requesting images larger than your standard 360 image size then you are allowed to request images from the API at a rate of one image per second.
These examples require the use of a browser (all browsers supported apart from IE11, Opera Mini and Android 4.4 Browser and older) and jquery.
Please take note that we are currently transitioning to a new system and high variation count customers will be required to use viewerType = 2 value with the requests. An example for this is shown in the downloadable samples. Customers who have this requirement will be notified as part of the delivery process.
In this section we will cover the most frequently asked questions for the CAPI.
CAPI Frequently Asked Questions
Because images that are larger than your default view port will be throttled which means that if you have enough credits they will show, you can read more about this in the throttling section of the integration guide.
Yes, you can find them here.
You will have to contact firstname.lastname@example.org
Key's should be base 64 encoded and added in the header as "Authorization: Basic YourKeyHere". The integration guide includes a few code samples to get you started.