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.
In order to not overload our system and to ensure all clients receive equal performance requests to the Content API are throttled. The throttling algorithm is based on a credit system where each client by default “earn” one credit per second. Each credit allows for a single image download. In order to allow for spikes in requests any unused credits are saved for a max credit of 10 seconds worth of credit per client.
- You earn one credit per second, but consume only one credit every two seconds. This means you will have a buffer of 5 credits available to handle request spikes.
- You earn one credit per second, but consume only one credit every fourth second. This means you will have a buffer of 7.5 credits available to handle request spikes.
- You earn one credit per second, but have not consumed any credits the last ten seconds. This means you have a full buffer of 10 credits available to handle request spikes. If you then have 11 requests in a single second then you will be throttled on the last request as the first ten requests would have consumed the available credits.
Any throttled request returns a 429 http status code.