...
API
| URL | HTTP Type | Description |
|---|---|---|
| /externalFileHandle | POST | Post an external File Handle. Note: The body of the request is an ExternalFileHandle object, wrapping the URL to be stored. |
| /fileHandle/{handleId} | GET | Get the FileHandle for a given FileHandle ID. Only the original creator of the FileHandle is authorized to get a FileHandle or assign a FileHandle to a Synapse Object such as WikiPage attachment or FileEntity. |
| /fileHandle/{handleId} | DELETE | Delete a FileHandle by its ID. This will also trigger the delete of the corresponding file in S3 (when relevant) and any preview automatically generated for the FileHandle. |
...
Chunked File Upload API
While it is possible to upload very larger files with a single HTTP request, it is not recommended to do so. If anything were to go wrong the only option would be start over from the beginning. The longer a file upload takes the less likely restarting will be acceptable to users. To address this type of issue, Synapse provides 'chunked' file upload as the recommended method for upload all files. This means the client-side software divides larger files into chunks and sends each chunk separately. The server code will then reassemble all of the chunks into a single file once the upload is complete. Any file that is less than or equal to 5 MB should be uploaded as a single chunk. All larger files should be chunked into 5 MB chunks, each sent separately. If any chunk fails, simply resend the failed chunk. While this puts an extra burden on client-side developers the results are more robust and responsive code. The following table shows the four web-service calls used for chunked file upload. For these calls the request and response objects are not the same, so both will be shown:
| Response (type) | URL | HTTP Type | Request (type) | Description | ||||
|---|---|---|---|---|---|---|---|---|
| 1 | ChunkedFileToken (application/json) | / | largefiletokencreateChunkedFileUploadToken | POST | CreateChunkedFileTokenRequest ( | content-type= 'application/json | ') | Create a new large file tokenChunkedFileToken. A large file token is required to upload a large file. |
| /largefilepart | POST (content-type= 'multipart/form-data') | Post a single part of a large file. The large file token and the part number should be included include with the file POST. | ||||||
| /largefilecomplete | POST(content-type= 'application/json') | After all part of a large file have been posted, this call is used to complete the process and retrieve the resulting FileHandle of the large fileThis token must be provided in all subsequent requests. | ||||||
| 2 | URL (text/plain) | /createChunkedFileUploadChunkURL | POST | ChunkRequest (application/json) | Create a pre-signed URL that will be used to PUT a single file chunk. This step is repeated for each chunk. | |||
| 3 | ChunkResult (application/json) | /addChunkToFile | POST | ChunkRequest (application/json) | After a chunk is PUT to a pre-signed URL, it must be added to file. You will need the returned ChunkResult to complete the upload. This step is repeated for each chunk. | |||
| 4 | S3FileHandle (application/json) | /completeChunkFileUpload | POST | CompleteChunkedFileRequest (application/json) | After all chunks have been added, complete the upload with this call. The resulting S3FileHandle can be used for any object that accepts FileHandles. |