FileHandle API (Alpha)

Note: The FileHandle 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.
fileName	The name of the file. This field is required.

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 Types

For any web services where a file is sent with a POST, the content-type must be 'multipart/form-data', see:HTTP Multipart. The content-type of all service responses will be 'application/json'.

Note: Unless otherwise specified all FileHandle services uses a new endpoint: https://file-prod.sagebase.org/file/v1. Also standard Synapse 'sessionToken' must be included in all requests.

API

URL	HTTP Type	Description
/fileHandle	POST	Post a list of Files (content-type= 'multipart/form-data'). For each File included in the POST, a FileHandle will be created and returned. The ID of the returned FileHandles can be used to assign the file to a Synapse objects such as WikiPage attachments or FileEntity.
/externalFileHandle	POST	Post an extremal file handle.
/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.

Planned Future API (not currently implemented)

URL	HTTP Type	Description
/largefiletoken	POST(content-type= 'application/json')	Create a new large file token. 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 file.