V5 onwards only
This tutorial demonstrates how to upload chunk files via the RESTful API.
The steps include:
Initiating the chunk upload session and getting the session ID
Sending the upload chunk requests
Finalising the chunk upload session
This tutorial does not show how to split a file into chunks and assumes that the developer has already done so and now needs to begin the upload process.
One way to do the chunk splitting is within a loop, where the requests and responses are sent and received within the loop.
The commands are provided in curl and can be run from the command prompt when the Synergy Server is running (or in a batch script).
Additional API documentation
To get a list of most of the API requests available, with the 12d Synergy server running, browse http://synergy.myserver.com/api-docs/ui/index.
(Replace synergy.myserver.com with the external server address and update the port numbers if necessary.)
1.1. Logging in and using access tokens for the API requests
A bearer access token is required to be sent up with each request. The tutorial for getting and updating tokens is here: Generate PAT in Web client
1.2. Initiating the chunk upload session and getting the session ID
The initiateChunkUpload request can be found in the API documentation under Files, marked 'Initiates a file upload in chunks'.
The body of the request should be similar to the following example.
Click 
in the line below to see the code.
ChunkUploadInitiationRequestModel
{
"FileName": "Survey_JobNo2305_onsite.mp4", // string
"ChunkSize": 1048576, // int (size of initial chunk in bytes)
"TotalSize": 47520296 // long (total size of the file in bytes)
}
The maximum chunk size allowed is 1,048,576 bytes
The curl command then looks something like this:
Initiate Chunk Upload Request
curl --location --request POST "http://synergy.myserver.com/api/v1/files/initiateChunkUpload" ^
--header "Authorization: Bearer <token>" ^
--header "Content-Type: application/json" ^
--data "{\"FileName\": \"Survey_JobNo2305_onsite.mp4", \"ChunkSize\": 1048576, \"TotalSize\": 47520296}"
If the request is successful a response model is returned, including the SessionId which will be required for the rest of the requests:
ChunkUploadInitiationResponseModel
{
"FileName": "Survey_JobNo2305_onsite.mp4",
"SessionId": "b6b84278-b0ba-4d17-b71a-0aa656ceaa32",
"ChunkSize": 1048576
}1.3. Sending an Upload Chunk Request
The uploadChunk request can be found in the API documentation under Files, marked 'Uploads a file chunk'.
The SessionID must be concatenated to the request URL as well as the chunk number (starting at 1).
This request expects the file chunk as multi-part form data (in the below example, stored as the variable chunk).
Upload Chunk Request
curl --location --request POST "http://synergy.myserver.com/api/v1/files/uploadChunk/b6b84278-b0ba-4d17-b71a-0aa656ceaa32/1" ^
--header "Authorization: Bearer <token>" ^
--header "Content-Type: multipart/form-data" ^
--form data=chunkA successful response will return true. Repeat the same request until all the chunks have been sent up.
When the number of successful responses equals the total number of chunks, then the finalise request can be sent up.
1.4. Finalising the Chunk Upload Session
The finalizeChunkUpload request can be found in the API documentation under Files, marked 'Finalize a chunk upload'.
The SessionID must be concatenated to the request URL.
The body should be the same file upload model as used when uploading files the regular way (see How to upload files to 12d Synergy via the Web RESTful API).
In the curl example below, the JSON body has been placed in a separate file called file_upload_model.json (which is sitting in the same folder as the curl request).
Finalise Chunk Upload Request
curl --location --request POST "http://synergy.myserver.com/api/v1/files/finalizeChunkUpload/b6b84278-b0ba-4d17-b71a-0aa656ceaa32" ^
--header "Authorization: Bearer <token>" ^
--header "Content-Type: application/json" ^
--data @file_upload_model.jsonThe FileUploadModel should include attributes for the file, if necessary, and the "ID" is the ID of the destination folder.
The example below shows the JSON body of the request. In this example, the folder has a required user attribute called "ApprovedBy" - the value for the attribute is the user ID (in this case, 1)
Click in the line below to see the code.
file_upload_model.json
{
"operation":0,
"file_name":"Survey_JobNo2305_onsite.mp4",
"keep_check_out":false,
"id":
{
"_id":81917,
"_server_id":1,
"_server_guid":"cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString":"81917_1"
},
"description":"file chunks uploaded by curl",
"file_attributes":
[
{
"auto_increment_start": 1,
"description": "",
"enum_items": null,
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"optional": false,
"order": 1,
"read_only": false,
"reprompt_on_change": false,
"type": 5,
"value": {
"_value": {
"_id": 1,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "1_1"
},
"enum_id": null,
"value_id": null
},
"visibility_constraint": null,
"workflow_id": null,
"attribute_id": {
"_id": 50530,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "50530_1"
},
"name": "ApprovedBy",
"display_name": "ApprovedBy",
"id": {
"_id": 50530,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "50530_1"
}
}
],
"change_attributes":null,
"workflow_capture_data":null
}A successful response will return true.