Web API for Manipulating Design and Mockup Files

Customer's Canvas provides an API to manipulate design and mockup files for the host web application. This API works based on the 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/designs|mockups/folder 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" to it.
Delete a file DELETE ~/api/ProductTemplates/designs|mockups/id Deletes a file with the given id.
Replace a file PUT ~/api/ProductTemplates/designs|mockups/id Replaces a file with the given id. If there is no such file, uploads the given one.
Get file list GET ~/api/ProductTemplates/designs|mockups Returns an array of file identifiers in the \designs\ or \mockups\ folder.
Get an image preview GET ~/api/ProductTemplates/designs|mockups/id?width=int&height=int Returns an image preview generated with the given size (in pixels).

Here id is the file identifier you normally use when loading a file into the editor. The identifier consists of a file name without extension and, optionally, a path to the file relative to the \designs\ or \mockups\ folders. For example:

  • BusinessCard is the id for the \designs\BusinessCard.psd file.
  • photobook\photobook_page_2 is the id for the \designs\photobook\photobook_page_2.psd file.

Security

The ProductTemplates controller works through the HTTPS only. Any POST, PUT, or DELETE request must include the X-CustomersCanvasAPIKey: "ApiSecurityKey" field in its header, where "ApiSecurityKey" is the unique key which you define in the web.config file:

XML
<configuration>
...
    <system.web>
        ...
    </system.web>
    <appSettings>
        <add key="ApiSecurityKey" value="ApiSecurityKey"/>
    </appSettings>
...
</configuration>
Important

The snippets below define the application key in JavaScript code. It could be highly insecure if they run on a public site. However, you can use this way in your admin panel, or just for demonstration purposes.

For real applications there should be a back-end code, that proxies requests to the ProductTemplates controller. So, your code decides whether a user has enough rights to manipulate a mockup or template file or not and if the user has enough rights, the code sends the request to the ProductTemplates controller.

Uploading Design

The following snippet displays a form that allows selecting a file and a script that uploads the selected file to the \designs\ folder on the server:

HTML
<!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/SimplePolygraphy/api/ProductTemplates";

        var apiKey = "ApiSecurityKey";

        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
            })
            .done(function(d) {
                console.log("File is uploaded successfully. Its id is " + d);
            })
            .fail(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>

Sample Requests

Here are several snippets, one per each function provided by the ProductTemplates controller, illustrating how to form proper requests.

Displaying a 250x250 pixels business card design preview

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:

HTML
<img src="https://example.com/SimplePolygraphy/api/ProductTemplates/designs/businesscard2_side1?width=250&height=250" />

The other functionality requires properly formed requests. All the snippets below use jQuery.ajax and utilize the following variables:

JavaScript
//baseUrl is the absolute URL to the ProductTemplates controller
var baseUrl = "https://example.com/SimplePolygraphy/api/ProductTemplates";

//apiKey is your application unique key defined in the web.config file; the key allows file operations (upload, delete, replace)
var apiKey = "ApiSecurityKey";
Getting a list of files in the \designs\ folder
JavaScript
$.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);
    });
});
Deleting a page from the photobook
JavaScript
$.ajax({ 
    type: "DELETE",
    headers:  { "X-CustomersCanvasAPIKey": apiKey },
    url: baseUrl +"/designs/photobook/photobook_page_2"
})
Uploading a mockup
JavaScript
$.ajax({ 
    type: "POST",
    url: baseUrl +"/mockups",
    headers:  { "X-CustomersCanvasAPIKey": apiKey },
    data: data, //a file to upload
    processData: false,
    contentType: false 
}).done(function(d) {
    //outputs the id of the uploaded mockup to the console
    console.log(d);
});
Replacing a page in the photobook
JavaScript
$.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 
})