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:

1. 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.
2. 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.

 

Access

In version 3 of the Content API, access requests can be made in the following two ways.

Unauthenticated Requests

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.

Authenticated Requests

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 support@cylindo.com with a request for access.

Integration requirements

Here is a summary of what is required to use CAPI:

• An understanding of how to use and consume APIs using javascript or any other programming language of your choice.
• 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 support@cylindo.com with a request for CAPI access.

Fallback image

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.

Javascript disabled clients

To maximize your user base then we recommend that you use our Content API (CAPI) to support browsers that does not execute javascript on the page. This can be done by implementing an image element in a "noscript" section immediately after the cylindo script e.g.

<script>
// initialization of the 360 HD Viewer in this script section 
</script>
<noscript>
	// if the user's browser cannot execute javascript, but only pure html then 
// this section is displayed instead.
	<img src="http://viewer-images.cylindo.com/assets/viewer/7/24854/
Kilin%20Armchair_1_jpg/large.jpg?accountID=4404&size=512">
</noscript>

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 support@cylindo.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.

CAPI Examples

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.

• jQuery
• Javascript
• .Net

In this section we will cover the most frequently asked questions for the CAPI.

 CAPI Frequently Asked Questions