The Dropbox Delta API

The Dropbox Delta API is a rather interesting API. It is interesting in the way it works, and it is interesting in what it tries to achieve.



Consider a scenario, when you need to trigger an event, depending on some change in your Dropbox account - be it a file addition/creation, a file edit, or a file change. The sad way to do it, is to pole your Dropbox folder, and then check for a particular file, and then compare metadata and so on.

The Delta API takes most of the trouble out of this, by allowing you to fetch a cursor that denotes the present state of your Dropbox folder, and has information about all the changes that have happened in it, since the last fetch.

So, to trigger an event when something has changed in your Dropbox folder, all you need to do is, call the Delta API repeatedly, and check the cursor - and depending on the what the cursor contains, trigger whichever event you want.

Since Python has the easiest learning curve when it comes to using new APIs, let's take a look at how one would go about doing the same in Python. In fact, it's just above 20 lines of code there.

Here goes.

import dropbox
import sys

access_token = 'YOUR ACCESS TOKEN'
client = dropbox.client.DropboxClient(access_token)

curr_cursor_file = open("cursor.txt", "r")
curr_cursor = curr_cursor_file.read()
curr_cursor_file.close()

next_cursor = client.delta(curr_cursor)
curr_cursor_file = open("cursor.txt", "w")
curr_cursor_file.write(next_cursor['cursor'])
curr_cursor_file.close()
 
if len(next_cursor['entries']) > 0:
 for entry in next_cursor['entries']:
  if entry[1] != None:
   print entry[0] + " has been added."
  else:
   print entry[0] + " has been removed."
else:
 print "No files have changed."


So what we are essentially doing is instantiating a new Dropbox client object with our unique access token. (To know how to get a unique access token check this link.) Next we are reading the current cursor value from the cursor.txt file. This cursor value is now passed in the main call to the delta API, and that returns the next cursor value relative to the passed cursor value - the value of which is now replaced in the cursor.txt file.

The next_cursor variable is basically a list of entries - where each entry denotes a change in the folder . A length of zero implies no change since the last call. If non-zero, we need to handle two cases - that of a file creation, or a file deletion. A file edit can be thought of as a deletion followed by a creation, so if we handle these two basic cases, we're good.

To distinguish between creation and deletion, we delve into the structure of each entry. According to the Dropbox Delta API page, each entry is an array. The first element of the array is the name of the file that has changed, and the second entry is the metadata changed. So, we can tell whether a file has been deleted, if the metadata of the changed file is null, right? Sounds simple enough? So that's what we check - if the metadata is null (in Python that would be the default None value) - then the file has been deleted. Else it's been added.

Now we can simply wire up this script to run after a fixed time interval, and presto! You have an automated event triggering application - that fires whenever there's a change in the Dropbox folder.

Comments