The new /delta API call (beta)

Posted by Kannan Goundan on February 08, 2012

From the very first release of the Dropbox API, developers have asked for ways to efficiently keep up with changes to files in Dropbox. Today we're releasing something that takes the API a step in that direction.

The new /delta API call returns a list of delta entries that describe what has changed in a user's Dropbox, allowing the app to update its local state to match. The app stills need to poll periodically, but using /delta is much more efficient than using /metadata for tracking an entire folder hierarchy.

We're releasing this in beta to get feedback. Things will probably change before the final release, so don't use it in production just yet. For now, it only works for app keys with "Development" status and only on App Folders.

Some things to watch out for:

  • /delta is a little trickier to use than our other API calls. Read the documentation closely.
  • The list of delta entries is intended to help an app get its internal state caught up with the Dropbox server's state. We don't recommend showing it to the end user. For example, you may get entries out of order — the "add" entry for a file before the "add" entry for the file's parent folder. You may also get "delete" entries for files you don't have in your local state.
  • Please use intelligent back-off for polling. While it'll be tempting to repeatedly poll /delta to get instant notification of changes, we'd appreciate polling intervals no less than 5 minutes on average.

Below are updated copies of the Python, Ruby, and Java SDKs. Each SDK comes with a "search cache" example program that keeps a local cache of all the file names in an App Folder and uses /delta to keep the cache up to date.

Give it a try. If something doesn't work or is confusing, let us know on the forum thread.