PIXILAB Wiki

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision 		Previous revision
blocks:api:upload [2022-06-27 20:08]
admin created 		blocks:api:upload [2025-02-04 13:57] (current)
admin [File Upload API]
Line 1: Line 1:
 ====== File Upload API ====== ====== File Upload API ======
-Blocks provides an HTTP API for uploading files, for example images. Uploaded files are temporarily stored in a subdirectory of the //temp// directory inside your Blocks root directory, and should then be moved or further processed by a script. As an example, [[blocks:app-note:publishphoto|this application note]] describes how to upload photos subsequently shown on a Display Spot. +Blocks provides an HTTP API for uploading files, for example images. Uploaded files are temporarily stored in a subdirectory of the //temp// directory inside your Blocks root directory. This directory is not externally accessible for reading data. Thus, uploaded files must then be moved or further processed by a script. As an example, [[blocks:app-note:publishphoto|this application note]] describes how to upload photos subsequently shown on a Display Spot. 
  
 +:!: **IMPORTANT**: Unless explicitly protected by an //upload// API key and value in the [[blocks: server_configuration_file|configuration file]], uploads are not restricted in any other way. If an //upload// API key/value is specified, all upload requests must add an //apiKey// query parameter to the URL, with the expected value, or the upload will be rejected.
 ===== Upload file using multipart/form-data ===== ===== Upload file using multipart/form-data =====
 **URL:** /rest/upload/multipart **URL:** /rest/upload/multipart
Line 23: Line 24:
 </code> </code>
  
-===== Upload file using application/x-www-form-urlencoded =====+===== Upload a text snippet as urlencoded data =====
  
 **URL:** /rest/upload/urlencoded/{target}/{filename} **URL:** /rest/upload/urlencoded/{target}/{filename}
Line 32: Line 33:
 The server returns the path inside the //temp// directory where the file was stored or, in case of an error, an error message along with status code indiating an error. The server returns the path inside the //temp// directory where the file was stored or, in case of an error, an error message along with status code indiating an error.
  
-Here's is a JavaScript example showing how to upload a text file with a unique file name using this method. The promise returned by the fetch call will eventually provide the path to the file if the upload was successful.+Here's is a JavaScript example showing how to upload a short text snippet (specified by the body) to a file with a unique file name using this method. The promise returned by the fetch call will eventually provide the path to the file if the upload was successful.
  
 <code> <code>
Line 44: Line 45:
 </code> </code>
  
 +===== Upload an image as urlencoded data =====
 +
 +Here's is an example showing how to upload a PNG image with a unique file name as urlencoded data. Once this is done, the script logs the server-side name of the file, which you would then normally use to call some custom [[blocks:advanced_scripting#resource|API endpoint]] on the server with this information for further processing of the uploaded image.
 +
 +<code>
 +<canvas id="canvas" width="640" height="480"></canvas>
 +<button id="upload">Upload canvas image</button>
 +
 +<script>
 +const canvas = document.getElementById("canvas");
 +const ctx = canvas.getContext("2d");
 +
 +// Draw something on the canvas.
 +ctx.fillStyle = "red";
 +ctx.arc(320, 240, 100, 0, 2 * Math.PI);
 +ctx.fill();
 +
 +document.getElementById("upload").addEventListener("click", function() {
 +    
 +    // Convert canvas content to Blob (containing PNG data).
 +    canvas.toBlob(async function(blob) {
 +        
 +        // Upload image as PNG.
 +        let res = await fetch("/rest/upload/urlencoded/test/*.png", {
 +            method: "post",
 +            headers: {
 +                "Content-Type": "application/x-www-form-urlencoded"
 +            },
 +            body: blob
 +        });
 +
 +        // Retrieve file name from response and log it in the console.
 +        let fileName = await res.text();
 +        console.log(fileName);
 +    });
 +});
 +</script>
 +</code>