We use Dropbox for a lot of things at Goya. We also use APIs for a lot of things. Last year we published an article explaining the basic steps of integrating the FileMaker platform with the Dropbox API.

The steps and endpoints in that article are still valid, but the Dropbox API uses a different approach for files bigger than 150Mb. One of the BaseElements plugin sponsors asked us to write an example of this process.

 

DropBox “upload_session”

The endpoint URL for the smaller files is :

https://content.dropboxapi.com/2/files/upload.

One call for the upload, that’s it.  But for files bigger than 150Mb, the APi documentation shows us 3 different URLs:

https://content.dropboxapi.com/2/files/upload_session/start
https://content.dropboxapi.com/2/files/upload_session/append
https://content.dropboxapi.com/2/files/upload_session/finish

A upload sessions is a series of requests to upload a single larger file. The start endpoint starts a new upload session with the given data, then append can be use to add more data, until finish saves all of it to a file in Dropbox.

Each time, the data should not be bigger than 150Mb. This means that we have to cut our larger file in chunks of up to 150Mb each, and then perform an API request for each one of the chunks.

How do we do that? With some help from the BaseElements plugin!

To separate the file in chunks, we need to use a system command called split. It is part of the Mac OS, and on Windows we can use a port called split.exe (in our example we used this port).

 

The split

To run an OS level command we’ll use the plugin function BE_ExecuteSystemCommand :

BE_ExecuteSystemCommand ( command { ; timeout } )

The syntax of the split command we use is this: split -b 150m <<LARGE_FILE_NAME>> <<PREFIX_FOR_CHUNKS>>

Two important notes:

  • we need to run split from the right context, so we’ll have to chain a change directory command (cd <<FOLDER>>) before we call split.
  • we need a way to return the list of file names for the chunks to FileMaker, so we’ll have to use something like ls on Mac or dir /b on Windows.

To chain more than one system command in the same request we can use ; on Mac, && on Windows.

Once the file is split and we have our chunks, we can loop through our chunks and perform the upload_session requests

 

Uploading the file

The process for a file split into n chunks is:

  • upload_session/start using chunk number 1
  • upload_session/append for chunks 2 to n-1
  • upload_session/finish for chunk n

The 3 endpoints work the same way: a POST request that uses 3 headers (AuthorizationDropbox-API-Arg and Content-Type) and a binary body consisting of the chunk.

The Dropbox-API-Arg header controls the specific parameters for each request:

  • for the start request, we need to tell Dropbox that there are other chunks coming, so we pass --header \"Dropbox-API-Arg: {\\\"close\\\": false}\" in the options. The start request returns a session_id
  • for the append request, we need to specify what session we are continuing using the session_id we received before. Also we need to specify what offset the new chunk needs to be added to. We can use GetContainerAttribute ( <<CHUNK n>> ; "filesize" ) in each loop to calculate the new offset
  • for the finish request we need to specify a path and a name for our file (the path is relative to the home folder for the Dropbox developer app of the token we are using).

Once we call the upload_session/finish, the file is actually copied to Dropbox.

 

Conclusion

This article should give you all the steps necessary to implement this process. A complete example file is available to sponsors of the BaseElements plugin, and is sitting in their DropBox share folder already.

Thanks to the sponsor who requested this integration!


Salvatore is our web services and integration expert, passionate about linking any API useful to our clients (or us!) to FileMaker. He loves to share ideas and a good story, and as a speaker at DevCon he manages to do both.