- When do I need an integration?
- What are Canto's capabilities?
- Are there existing standard integrations?
- Using the Canto API - what do I need to know?
- What are Canto Webhooks?
- When do I need a CDN?
- Use cases
- How do I get started?
When do I need an integration?
Canto serves as a central place to manage your digital assets. But in many cases, those assets are also needed in other places in the organization, such as the website or product management. For Canto to remain the single point of truth, the other systems should also access assets from Canto. If each system were to manage its own assets, there would be redundant files, duplicate storage, and use of possibly outdated assets.
To allow Canto assets to be accessed from other systems without having to log into Canto and download the assets there, it can be useful to create a connection between Canto and another system. This connection provides direct access to Canto assets from the third-party system in question, and in the best case scenario, links can be established to the assets.
There are numerous options for implementing such integration. Since requirements also vary widely from customer to customer, we cannot provide a general guide for developing an integration. The following passages provide an overview of the possibilities Canto offers and address the most common use cases.
As a general rule, Canto does not provide developer resources for custom integrations. If you plan to integrate a third-party system with Canto, you must develop it on your own. However, we are happy to provide developer support for our API. This means: We will discuss your requirements with you in a joint meeting and advise you on how best to implement them using our API. Advice regarding the third-party system or programming language you use is not part of this support, nor is an analysis of your source code.
What are Canto's capabilities?
The Canto API
The Canto API is a RESTful web service that allows you to perform both read and write operations on your Canto tenant. In addition to retrieving and writing metadata, it is also possible to upload assets or retrieve the folder/album structure, among other things. The API is a passive component. This means that the API must be addressed by the third-party system.
Webhooks allow you to send notifications to a remote terminal when there are changes to Canto content. For various events, e.g. uploading, modifying, deleting an asset, assigning or removing an album, creating albums, a notification is sent as json, xml or txt format to a specific URL. This remote terminal has to receive the messages and process them. This way, the third-party system content can always be kept in sync with Canto content and outdated or unlicensed content in the third-party system can be avoided.
Note: The webhooks can be used well as a supplement to the Canto API.
Media Delivery Cloud - asset delivery via CDN
The Media Delivery Cloud (MDC) is Canto's Content Delivery Network (CDN) and is used to publish assets to the third-party system. The MDC can be used to link the assets in the third-party system.
All details about the requirement and usage of the MDC can be found in this article.
The Universal Connector is a sample application developed by Canto that can be used as a basis for developing your own integrations. The Universal Connector provides an asset picker with search and navigation functions. The source code is available free of charge in our Help Center and can be further developed or adapted independently.
Are there existing standard integrations?
Canto has already developed a number of universally usable integrations to some third-party systems. An overview of existing integrations can be viewed on our website.
Using the Canto API - what do I need to know?
There is extensive documentation available online for our API. This documentation also includes an extensive Best Practices section and some Integration Guidelines that we kindly ask you to follow.
An appointment with our Developer Support will also help you work out the right path for your integration.
Below are some basic information on how to work with the API:
The Oauth server is based on the domain of your Canto account
Authorization is done using OAuth2. For this, Canto offers several OAuth servers, which are based on the domain of your Canto account. For example, if your Canto account is in the .com domain, then you must also use the .com Oauth server for authorization. An API Key, consisting of ID and Secret, is required for authorization. The API Key will be provided to you by our support.
Distinction between Authorization Code and Client Credentials
Basically, there are two modes for authorization:
- Authorization Code
- Client Credentials
The Authorization Code must be retrieved via the Oauth page by entering username and password, so it requires manual intervention. It is suitable, for example, for user-controlled or front-end integrations. In contrast, authorization via client credentials can be completely automated and is therefore optimal for backend integrations.
After successful authorization you will receive an Access Token which is relevant for the further use of the API. This token is valid for 30 days.
Different rate limits of the API endpoints
Each API endpoint has its own rate limit, which indicates how many times the endpoint can be retrieved per minute. If the rate limit is reached, the API sends a corresponding error message (HTTP 429). If this is the case, the request must be repeated after a waiting period.
Basic error handling
Besides the rate limit, errors can occur for other reasons during communication with a web service. See the API documentation for a list of possible error codes and their causes. To avoid problems with the integration, consistent error handling should be part of the implementation.
What are Canto Webhooks?
Canto Webhooks allow automated notifications to be sent from Canto to a remote site. These notifications are preceded by a change in Canto, so for example changing metadata or deleting an asset can trigger an automated message.
The receiving remote site must be developed by the customer. It must be able to receive and process these messages.
Using the webhooks in combination with the API makes sense if the third-party system is to be notified about changes or new/deleted assets.
Note: Webhooks are triggered directly when a corresponding change is made in Canto. Canto does not persist the webhooks. It is recommended to create an automated comparison on the third-party system side that checks the consistency of the data on a regular basis (e.g. once a day).
When do I need a CDN?
A Content Delivery Network (CDN) is used for global, high-performance delivery of assets, e.g. on a website, in a PIM system or when forwarding to marketplaces.
The Canto CDN (Media Delivery Cloud) allows you not only to deliver assets, but also to adjust them on-the-fly in terms of size, format or image cutout.
Another advantage of using MDC is that assets can be linked (if possible in your third-party system) instead of being copied. This means that you always receive the most up-to-date asset, and additional storage space and redundant data storage are avoided.
Below is a list of some examples of common use cases for an integration.
Retrieve assets from Canto and display them in third-party system
e.g. CMS (website) or e-commerce system
An asset picker is needed to select Canto assets in the third-party system - this must be developed either in-house or based on the Universal Connector (API)
A search/filtering of the Canto data should be available to the users of the third-party system (API)
Publishing of assets in various sizes (thumbnail, preview image, etc.) is done by linking via an MDC link, no download necessary (if supported by the third-party system) (MDC)
Display of Canto folder and album structure in third-party system
e.g. CMS (website) or PIM system
- Retrieval of the entire order structure or a partial structure (e.g. product images) and display in the third-party system (API)
Navigation and display of folder contents (API)
Assign Canto assets to products
e.g. PIM system
- Search/retrieve the metadata and links to the assets (API, MDC)
- Update metadata between Canto and PIM (uni- or bi-directional) (API, Webhooks)
- Requires unique attribute to link Canto assets to products, e.g. article number in Canto + Canto ID in PIM system
- Important question: is there a 1:1 or 1:n relation between article and asset? (if 1:n e.g. store part numbers comma separated on asset)
- If Canto assets are linked in the PIM, no additional data storage necessary (MDC)
Distribution of product images in the web shop
e.g. e-commerce system
- Search/retrieve assets via unique attribute (e.g. item number) (API, MDC).
Requires unique attribute to link Canto assets to products in store
Further assignment possible via additional metadata, e.g. position in store via image number/type of image (front, side, top..) (API)
Distribution of safety data sheets for downloading
e.g. PIM system or e-commerce system
- Search/retrieval of safety data sheets using filter criteria based on metadata (API, MDC if applicable).
- Assignment possible e.g. via article number or other metadata fields
- May require unique attribute to link Canto assets with products related to document
How do I get started?
Before you even start implementing an integration, a conceptual design should be in place. Make yourself aware of what goal you are pursuing with the integration and define your use cases.
If no internal development resources are available, it may be a good idea to hire an appropriate service provider. It is recommended to choose a service provider who is familiar with your third-party system and has basic know-how in the area of connecting RESTful web services.
In the next step, please contact our developer support. In a joint appointment with your developer we will talk about the best possible solution for your integration. In preparation for this appointment, you will find a series of questions below that we would like to discuss with you:
- Which third-party system will be connected to Canto?
- What type of integration are we talking about? - Backend integration (system to system, batch) or front-end/user-driven processes?
What specific requests do you want to make to our API?
In which time interval will the respective requests be executed? If this depends on the user load, a range would be useful: normal vs. high load
If you are uploading content to Canto:
What is the average number of uploads?
At what interval do you plan to query the upload status?
Do you need to link assets and/or thumbnails?
If yes, what kind of linking (preview/thumbnail/original)?
Approximately how many assets will be linked?
Do you need special renditions or cropping?
How many requests per minute are needed (on average)?
Do you also store the assets in the third-party system?
Is a scheduled sync of data required? If so, how do you plan to implement this (push/pull mechanism)?