New Patterns: Interacting with Files

In 2022, Dropbox Sign made important investments to improve developer experience. We adopted and maintain an official OpenAPI spec for the Dropbox Sign API, which powers our documentation and SDKs.

This architecture ensures ongoing parity between the Dropbox Sign API and the resources used to build with it. However, we had to make some changes to the way users interact with files when using the API.

Changing File Patterns

The changes introduced by the OpenAPI, and subsequently all new SDKs, enforce different approaches to uploading (passed within the API request) and downloading files. The changes are as follows:

  • The files parameter only accepts binary.
  • The Download feature are now broken out across multiple endpoints.

​​In this document, we’ll identify each change and provide some context around why it was necessary. If you’re migrating to a new SDK, please refer to the table below and use the examples in your SDK’s migration guide.

Passing Files with API Requests (“Uploading” Files)

Many endpoints in the Dropbox Sign API allow you to send a file with your API request. Passing a file using file_urls remains the same. However, directly passing a file with the files parameter has been changed.
Legacy SDKsNew SDKs
The file parameter required a path to your local file.
  • Converting file into binary was handled for you
The files parameter requires a binary of your local file.
  • Converting file into binary is your responsibility
  • Handled differently by each SDK

This change helps improve security, but also gives you more flexibility around where and how you process files. The small jump in complexity is a worthwhile tradeoff for having more control over the file processing in your integration

The table below outlines the options for doing this based on SDK:

Uploading files within each SDK

SDKUpload OptionsMigration Guide
Python
  • Option to implement the io module to open your files as a binary format and passing this information to the files parameter
Python SDK Migration Guide
Ruby
  • Files should be an instance of File
  • File.open or File.new can be used to construct a file instance
Ruby SDK Migration Guide
Node
  • Create a binary stream using the fs module’s createReadStream(), or upload from buffer using either readFileSync() or Buffer.from()
  • Pass the stream or buffer into the files parameter
Node SDK Migration Guide
JavaAll methods below utilize the built-in java.io.File
  • addFilesItem method
  • files method - Accepts a List of files
  • setFiles method - Accepts a List of files
Java SDK Migration Guide
Dotnet
  • Create a stream and convert to System.IO.Stream
  • files parameter takes a List<Stream>
Dotnet SDK Migration Guide
PHP
  • Must create a SplFileObject object and pass into setFiles() method
PHP SDK Migration Guide

Downloading Files

The Dropbox Sign API can be used to download files (documents, templates) in several different formats. Those formats include:

  • A binary file
  • A hyperlink to a downloadable file
  • A data uri (base64 encoded string)
Legacy SDKsNew SDKs
  • One endpoint was used for downloading signature request files (Download Files)
  • One endpoint was used to download template files (Get Template File)
  • Parameters were passed that controlled the format the files should be returned as (file, file_url, or data_uri)
  • Both Download Files and Get Template Files are split into 3 separate endpoints, each dedicated to returning files in a specific format
  • See the table below called Endpoints - Download Files and Get Template Files to see how the functionality is divided

This change was necessary because our new, OpenAPI-powered architecture couldn’t support returning different file types in the response. We decided the best long-term solution was to split the functionality across multiple endpoints that were purpose-built to return a specific format.

Endpoints - Download Files and Get Template Files

Download Files endpointsDownload Template Files endpoint
Download filesDownload Template files
Download files as data_uriDownload template files as data_uri
Download files as file_urlDownload template files as file_url

Building with New File Patterns

The changes made to the Dropbox Sign API around file interaction break past patterns of usage. We know that can be disruptive and sometimes frustrating. However, these changes were made because the API Engineering team found them to be the best long-term solutions that will ultimately contribute to the success of our API customers. If you have questions or need help, please submit a request.