Note: The File API is currently in alpha. Not all feature 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 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 ID |
| createdBy | The ID of the user that created this FileHandle. Only this user that created a FileHandle can assign it to a file entity or wiki attachment. |
| createdOn | The date the file handle was created on. |
| concreteType | FileHandle is an interfaces, with at least three implementations. This field is used to indicate which concrete implementation is used. |
There are currently three concrete implementation 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 |
ExternalFileHandle
An external file handle is used to represent an external URL. Notice 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 with a PrevewFileHandle. The creator of the ExternalFileHandle will be listed as the creator of the preview.
S3FileHandle
When a file is stored in Synapse, by default it is stored in Amazon's S3. The S3FileHandle captures the extra information about the S3 file. Just like ExternalFileHandles, Synapse will attempt to automatically create a preview of all S3FileHandles.
PreviewFileHandle
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 PreviwFileHandle. Currently, Synapse will generate previews based on the original file's contentType. See Internet Media Type.
HTTP Multipart (not REST)
Since the file web services deal with uploading files they are implemented as HTTP Multipart. This is a divergence from most of the Synapse web services calls which are simple REST calls. Most HTTP clients including browsers can natively handle multipart content types.