Hosted Files

The Hosted files API provides public asset hosting for an app (for example, it is the basis for storing a custom logo for each study). The assets must be added by developers, but the assets themselves are publicly available for download by a client without further authentication.

Hosting a file on the Bridge server involves several steps:

  1. The developer should create a FileMetadata object using the file metadata API;
  2. The developer should then create a FileRevision object for that metadata via the file revision API;
  3. The revision will be returned with a pre-signed URL to upload the content of the file to Amazon's S3 file hosting service (the URL expires in 10 minutes);
  4. The developer should PUT the file contents to S3;
  5. The developer should call the API to mark the file content upload as completed. (This can also be called to clean up orphaned revision records. If the S3 upload has failed, the revision record will be deleted.)

Once a file revision exists on the server, the app developer can link to it via the app configurations. The link to a file revision has a stable URL that can also be used directly by a client app or web app.

Using the Java REST SDK, this can be broken down into two steps. First, developers need to create a metadata object describing your file in all its revisions:

ForDevelopersApi devsApi = developer.getClient(ForDevelopersApi.class);

FileMetadata meta = new FileMetadata();

final GuidVersionHolder keys = devsApi.createFile(meta).execute().body();

Once this object exists and you have the GUID of the file, the Java SDK contains a utility method to perform the creation of a single revision for that file:

File file = new File("files/my-file.pdf");

FilesApi filesApi = developer.getClient(FilesApi.class);
String downloadURL = RestUtils.uploadHostedFileToS3(filesApi, meta.getGuid(), file);

This includes the upload of the file's contents to S3, so the downloadURL that is returned is the URL to retrieve the file via HTTP.