Customer's Canvas provides a Web API to manipulate design and mockup files. This API works based on HTTPS requests and is handled by the ProductTemplates controller (~/api/ProductTemplates
). It has the following functionality:
Function | Request type | URL | Description |
---|---|---|---|
Upload a file | POST |
~/api/ProductTemplates
|
Uploads a file to the \designs\ or \mockups\ folder or their subfolders. If a file with a given name already exists, the name of the uploaded file is changed by adding _1 , _2 , etc. to it. |
Download a file | GET |
~/api/ProductTemplates
|
Downloads a file with the given ID. The downloadArchiveWithLinks parameter enables file archiving if true . Such an archive also contains linked images referenced from the IDML template. This parameter is false by default. |
Delete a subfolder | DELETE |
~/api/ProductTemplates
|
Deletes a subfolder in the \designs\ or \mockups\ folder by the given ID. If there is no such a subfolder, this request will try to delete a file with the given ID (for more details, see the following endpoint). |
Delete a file | DELETE |
~/api/ProductTemplates
|
Deletes a file with the given ID. If no file extension is provided, this request will try to delete a file in the following order: .psd , .png , .jpeg , .jpg , .svg , .pdf , .bmp , .tiff , .tif , .gif , .eps , and .ai . For designs, this request will try to delete .idml and .json files first. |
Replace a file | PUT |
~/api/ProductTemplates
|
Replaces a file with the given ID. If there is no such file, uploads the given one. |
Get a file list | GET |
~/api/ProductTemplates
|
Returns an array of file identifiers in the \designs\ or \mockups\ folder. When you specify the subfolder parameter, then only files from this subfolder are listed. If ext is true , then file extensions are returned in the response. |
Get an image preview | GET |
~/api/ProductTemplates
|
Returns an image preview generated with the given size (in pixels). The mode is an optional parameter; the default value is File . |
Move or copy a file | PATCH |
~/api/ProductTemplates
|
Moves or copies a file, depending on the copy parameter. If overwrite is false and a file with a given name already exists, then the new file name is changed by adding _1 , _2 , etc. to it. If moveWithLinks is true , this method moves linked images with the referencing IDML template. copy, overwrite, and moveWithLinks are optional parameters; they are false by default. |
In the request header, this controller requires X-CustomersCanvasAPIKey - a unique API key defined in the AppSettings.config.
The ProductTemplates controller supports the following parameters:
\designs\
or \mockups\
folders. For example:
BusinessCard
is the id for the \assets\designs\BusinessCard.psd
file.photobook\photobook_page_2
is the id for the \assets\designs\photobook\photobook_page_2.psd
file.false
.500
by default.File
and there is the MergedImageFrame in your PSD file, then Customer's Canvas returns this preview. Otherwise, the editor provides previews through rendering the designs. The default value is File
.false
..idml
, .psd
, .png
, .jpeg
, .jpg
, .svg
, .pdf
, .bmp
, .tiff
, .tif
, .gif
, .eps
, and .ai
).500
by default.When moving or copying files, you can omit path, name, or both parameters. If the path is not specified, then the destination folder is \designs\
or \mockups\
. If you omit the name parameter, the resulting file takes the same name as id.
The snippets below define the API security key in JavaScript code. It could be highly insecure if they are run on a public site. However, you can use them this way in your admin panel, or just for demonstration purposes.
This snippet displays a form that allows for selecting a file and a script that uploads this file to the \designs\
folder on the server.
<!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <script type="text/javascript" src="https://code.jquery.com/jquery-2.2.0.js"> </script> <script language="javascript"> var baseUrl = "https://example.com/cc/api/ProductTemplates"; var apiKey = "UniqueSecurityKey"; var uploadTemplate = function(root, folder) { var data = new FormData(document.getElementById(root + "_upload")); $.ajax({ url: baseUrl + "/" + root + "/" + encodeURIComponent(folder), type: "POST", headers: { "X-CustomersCanvasAPIKey": apiKey }, data: data, processData: false, contentType: false, success: function(d) { console.log("The " + d + " file was uploaded successfully."); }, error: function() { console.error("Upload failed."); } }) } </script> </head> <body> <div id="designs"></div> <hr /> <h3>Upload a Design</h3> Folder: <input type="text" id="designfolder" /> <form id="designs_upload" enctype="multipart/form-data"> File: <input type="file" name="file" /> </form> <input type="button" value="Upload Desing" onclick="uploadTemplate('designs', document.getElementById('designfolder').value)" /> </body> </html>
Here are several examples, one per each function provided by the ProductTemplates controller, illustrating how to form proper requests.
There is no need to form a request in JavaScript to get a design preview. You can do it by triggering the URL as follows:
<img src="https://example.com/cc/api/ProductTemplates/designs/businesscard2_side1?width=250&height=250" />
The other functionality requires properly formed requests. The examples in this topic use jQuery.ajax and the following variables:
//baseUrl is the absolute URL to the ProductTemplates controller var baseUrl = "https://example.com/cc/api/ProductTemplates"; //apiKey is your unique application key defined in the AppSettings.config file; //this key allows file operations (upload, download, delete, replace) var apiKey = "UniqueSecurityKey";
$.ajax({ type: "GET", url: baseUrl +"/designs" }).done(function(d) { //outputs the list of files in the /designs/ folder to the console d.forEach(function(id) { var link = "/designs/" + id + ".psd"; console.log(link); }); });
If the ext parameter is omitted or false
, then the response contains an array of strings representing file identifiers. Otherwise, the array elements contain identifiers and extensions in the following format:
[ { "id": "businesscard2_side1", "ext": "psd" }, { "id": "businesscard2_side2", "ext": "psd" } ]
$.ajax({ type: "DELETE", headers: { "X-CustomersCanvasAPIKey": apiKey }, url: baseUrl +"/designs/photobook/photobook_page_2" })
$.ajax({ type: "DELETE", headers: { "X-CustomersCanvasAPIKey": apiKey }, url: baseUrl +"/designs/photobook" })
$.ajax({ type: "POST", url: baseUrl +"/mockups", headers: { "X-CustomersCanvasAPIKey": apiKey }, data: data, //a file to upload processData: false, contentType: false, success: function(d) { //outputs the ID of the uploaded mockup to the console console.log(d); } });
The response contains the identifier of the uploaded file.
$.ajax({ type: "GET", url: baseUrl +"/designs/bbqinvitation", headers: { "X-CustomersCanvasAPIKey": apiKey}, xhrFields: { responseType: "blob" }, success: function (data) { var a = document.createElement("a"); var url = window.URL.createObjectURL(data); a.href = url; a.download = 'bbqinvitation.psd'; document.body.append(a); a.click(); a.remove(); } });
$.ajax({ type: "PUT", url: baseUrl +"/designs/photobook/photobook_page_2", headers: { "X-CustomersCanvasAPIKey": apiKey }, data: data, //a file to replace the old one with processData: false, contentType: false })