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/startusing chunk number 1upload_session/appendfor chunks 2 to n-1upload_session/finishfor chunk n
The 3 endpoints work the same way: a POST request that uses 3 headers (Authorization, Dropbox-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
startrequest, 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 asession_id - for the
appendrequest, we need to specify what session we are continuing using thesession_idwe received before. Also we need to specify what offset the new chunk needs to be added to. We can useGetContainerAttribute ( <<CHUNK n>> ; "filesize" )in each loop to calculate the new offset - for the
finishrequest 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.