From d707613b277b43195d173d5dbfe0fdaa97c01148 Mon Sep 17 00:00:00 2001 From: Javad Asgari Shafique Date: Thu, 5 Sep 2024 20:53:46 +0200 Subject: [PATCH] Add documentation for new files.simplyprint.io (API Files) --- source/includes/_api_files.md | 93 +++++++++++++++++++++++++++++++++++ source/includes/_files.md | 38 +++++++++++++- source/includes/_printers.md | 3 +- source/includes/_queue.md | 5 +- source/index.html.md | 1 + 5 files changed, 136 insertions(+), 4 deletions(-) create mode 100644 source/includes/_api_files.md diff --git a/source/includes/_api_files.md b/source/includes/_api_files.md new file mode 100644 index 00000000000..46ecf0596fb --- /dev/null +++ b/source/includes/_api_files.md @@ -0,0 +1,93 @@ +# API Files + +The base URL for the SimplyPrint Files API is `https://files.simplyprint.io/{id}/`. Use the exact same authentication as the normal api endpoint. It is very important you ensure you send files with the correct file extension. The API will not be able to determine the file type based on the content. + +## Upload a file using the API + +`POST {id}/files/Upload` + +> Example request to upload a file less than 100MB + +```shell +curl -X POST "https://files.simplyprint.io/{id}/files/Upload" \ + -H 'accept: application/json' \ + -H "X-API-KEY: {API_KEY}" \ + -F "file=@/path/to/file.gcode" +``` +> Success response + +```json +{ + "status":true, + "message": null, + "file": { + "id": "f568ead4bbc2d881efc8a9a05f3bd585334cd8c662347ba2dfad7250176b0abd", + "name": "file.gcode", + "size": 13439 + } +} +``` + +> Multiple parts for a single file larger than 100MB. The first filename is the filename of the entire file. + +```shell +curl -X POST "https://files.simplyprint.io/{id}/files/Upload" \ + -H 'accept: application/json' \ + -H "X-API-KEY: {API_KEY}" \ + -F "file=@/path/to/part1.3mf" + -F "totalSize=3352316" +``` +> Success response with continueToken + +```json +{ + "status":true, + "message":null, + "continueToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzM4NCJ9.eyJ0eXBlIjoiYWN0ao9uX3Rva2VuIiwiYWN0aW9uIjoiZmlsZV9jb250aW51ZV91cGxvYWQiLCJ1c2VyIjo2OTc2LCJjb21wYW55IjoyLCJkYXRhIja7ImJ1Y2tldEhhc2giOiI0MGQ2MzgwNmQwYWUxODhkNjc5YzY0NjA0M2RiYjUxMTc0NTViNTc1NjNlODEzZDc2MGRjMTJkMzVaYjdmY2Y0IiwidG90YWxTaXplIjoxNjc2MTU4NH0sImlhdCI6MTcyNTU2MjEzMywiZXhwIjoxNzI1NjQ4NTMzfQ.9qyNyx9A4Ox_6GrFSxXpxlpLcAKaSr8ln84X3yuWdhT_2O3L8-lGWaXAbQk9VvR-3pu1-a9p40amnt6Fghy49InjzCfNMRp-6-Ft_uMRf6PbmcCCrksvRxNP38ImoXy6" +} +``` + +> Continue uploading the file (send next part with only the continueToken) + +```shell +curl -X POST "https://files.simplyprint.io/{id}/files/Upload" \ + -H 'accept: application/json' \ + -H "X-API-KEY: {API_KEY}" \ + -F "continueToken=eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzM4NCJ9.eyJ0eXBlIjoiYWN0ao9uX3Rva2VuIiwiYWN0aW9uIjoiZmlsZV9jb250aW51ZV91cGxvYWQiLCJ1c2VyIjo2OTc2LCJjb21wYW55IjoyLCJkYXRhIja7ImJ1Y2tldEhhc2giOiI0MGQ2MzgwNmQwYWUxODhkNjc5YzY0NjA0M2RiYjUxMTc0NTViNTc1NjNlODEzZDc2MGRjMTJkMzVaYjdmY2Y0IiwidG90YWxTaXplIjoxNjc2MTU4NH0sImlhdCI6MTcyNTU2MjEzMywiZXhwIjoxNzI1NjQ4NTMzfQ.9qyNyx9A4Ox_6GrFSxXpxlpLcAKaSr8ln84X3yuWdhT_2O3L8-lGWaXAbQk9VvR-3pu1-a9p40amnt6Fghy49InjzCfNMRp-6-Ft_uMRf6PbmcCCrksvRxNP38ImoXy6" \ + -F "file=@/path/to/part2.3mf" +``` + +> Sucessful final response as we ensured to only send exactly the total size of the file. + +```json +{ + "status":true, + "message":null, + "file": { + "id": "f568ead4bbc2d881efc8a9a05f3bd585334cd8c662347ba2dfad7250176b0abd", + "name": "part1.3mf", + "size": 3352316 + } +} +``` + +### Request + +| Parameter | Type | Required | Description | +| --------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `file` | file | yes | Uploaded file (Max 100mb) | +| `continueToken` | string | no | Optional token you'll get if you need to continue the upload for files greater than 100MB. | +| `totalSize` | integer | no | Send this if you want a continueToken, by providing the total size of the entire file you want to upload | + +### Response + +| Parameter | Type | Description | +| ------------ | ------- | -------------------------------------------------------------| +| `status` | boolean | True if the request was successful. | +| `message` | string | Error message if `status` is false. | +| `continueToken` | string | For every subsequent request that still has some pending size based on the total size this will be returned instead of the file. | +| `file.*` | object | Final file object after entire file has been uploaded | +| `file.id` | string | The API File ID you'll need to use other SimplyPrint APIs | +| `file.name` | string | Name used to reference the file | +| `file.size` | int | Total size of uploaded file | + diff --git a/source/includes/_files.md b/source/includes/_files.md index 863d3f7e09c..6c1ffa9a7ff 100644 --- a/source/includes/_files.md +++ b/source/includes/_files.md @@ -1,9 +1,45 @@ # Files +## Add an API File to files + +`POST {id}/files/Upload?folder={folder}` + + +| Parameter | Type | Required | Description | +| --------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `folder` (GET) | integer | no | Folder ID to get files for. **Defaults to 0 (root folder)** | +| `fileId` (POST) | string | yes | File ID from [API Files](#api-files) + +### Response + +| Parameter | Type | Description | +| ------------ | ------- | ---------------------------------------------------------- | +| `status` | boolean | True if the request was successful. | +| `message` | string | Error message if `status` is false. | +| `id` | string | User file ID of newly added file | + + +```shell +curl -X POST https://api.simplyprint.io/{id}/files/Upload?folder=5290 \ + -H 'accept: application/json' \ + -H 'X-API-KEY: {API_KEY}' \ + -F 'fileId=43aaad56548c959f655d0524027b726a7514493ec8436f4942f876bb07eab731' +``` + +> Success Response + +```json +{ + "status":true, + "message":null, + "id":"6f7d79212f384c6b8eae2811c37d9338" +} +``` + ## List Files and Folders ```shell diff --git a/source/includes/_printers.md b/source/includes/_printers.md index 5017103bcc0..a39ceaacbd7 100644 --- a/source/includes/_printers.md +++ b/source/includes/_printers.md @@ -324,7 +324,7 @@ curl https://api.simplyprint.io/{id}/printers/actions/CreateJob?pid=1234&filesys ``` This endpoint can be used to create a print job for one or more printers. The printers have to be in the `operational` state. @@ -341,6 +341,7 @@ To start a print job you must either specify a `filesystem` ID, a `queue_file` I | `filesystem` | string | no | The filesystem ID of the file to print. | | `queue_file` | integer | no | The queue ID of the queue item to print. | | `next_queue_item` | boolean | no | If true, the next queue item will be printed.
**This requires the Print Farm plan** | +| `file_id` | string | no | File ID from [API Files](#api-files) - used to start a file without adding it as a queue item or user file. #### Extra settings for `next_queue_item` diff --git a/source/includes/_queue.md b/source/includes/_queue.md index 4cc3e636f39..a666c3403a6 100644 --- a/source/includes/_queue.md +++ b/source/includes/_queue.md @@ -34,7 +34,7 @@ curl https://api.simplyprint.io/{id}/queue/AddItem \ This endpoint adds a file to the queue. The file can either be a file on the filesystem or an uploaded stl/3mf/obj/gcode/gco/nc/npg file. @@ -47,9 +47,10 @@ This endpoint adds a file to the queue. The file can either be a file on the fil | Parameter | Type | Required | Description | | ------------ | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `filesystem` | string | no | The filesystem id of the file to add to the queue. | +| `filesystem` | string | no | The [filesystem](#files) id of the file to add to the queue. | | `amount` | integer | no | The amount of prints to add to the queue.
**Default: 1** | | `group` | integer | no | If you have Queue Groups - ID of the group the item should be added to.
**Default: 0 - required if you have Queue Groups** | +| `fileId` | string | no | Optional File ID from [API File](#api-files) - use this to add a file uploaded via the API. | ### Response diff --git a/source/index.html.md b/source/index.html.md index 546ac730ee3..2a6d541312d 100644 --- a/source/index.html.md +++ b/source/index.html.md @@ -12,6 +12,7 @@ includes: - printers - filament - files + - api_files - queue - account - jobs