Note: The FileHandle API is currently in alpha. Not all
...
features are supported.
FileHandle
The FileHandle is an object that represents a file that has either been upload to Synapse, or resides external to Synapse. The FileHandle provides basic metadata about file:
...
| Field | Description |
|---|---|
| id | The unique identified identifier of a file handle. This ID is used to reference a file handle. |
| etag | The etag of a file handle will change if the file handle changes. For the most part FileHandles are immutable, with the only exception being assigning a preview file handle FileHandle ID. |
| createdBy | The ID of the user that created this FileHandle. Only this the user that created a FileHandle can assign it to a file entity or wiki attachment. |
| createdOn | The date on which the file handle was created on. |
| concreteType | FileHandle is an interfaces, interface with at least three implementations. This field is used to indicate which concrete implementation is used. |
| fileName | The name of the file. This field is required. |
There are currently three concrete implementation implementations of FileHandle:
| Object name | concreteType |
|---|---|
| ExternalFileHandle | org.sagebionetworks.repo.model.file.ExternalFileHandle |
| S3FileHandle | org.sagebionetworks.repo.model.file.S3FileHandle |
| PreviewFileHandle | org.sagebionetworks.repo.model.file.PreviewFileHandle |
...
An external file handle is used to represent an external URL. Notice Note that ExternalFileHandle implements HasPreviewId. Synapse will try to automatically generate a preview for any external URL that can be publicly read. The resulting preview file will be stored in Synapse and respresented represented with a PrevewFileHandle. The creator of the ExternalFileHandle will be listed as the creator of the preview.
...
When Synapse creates a preview file for either an ExternalFileHandle or an S3FileHandle, the resulting preview file will be stored in S3 and be assigned a PreviwFileHandlePreviewFileHandle. Currently, Synapse will generate previews based on the original file's contentType. See Internet Media Type.
...
Note: Unless otherwise specified all FileHandle services uses use a new endpoint: https://file-prod.sagebase.org/file/v1. Also standard Synapse 'sessionToken' must be included in all requests.
...
While it is possible to upload very larger large 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:
...