An easy-to-use client library for the official Dropbox API.
Latest commit 702c0f9 May 29, 2012 @RISCfuture Merge pull request #47 from bcoe/master
Added Support for Shares
Failed to load latest commit information.
examples Updated README and added example Jan 14, 2011
lib Added support for… Dec 13, 2011
spec Added support for… Dec 13, 2011
.document Initial commit to dropbox. Nov 12, 2009
.gitignore Modernized gem with Bundler and RSpec 2.0 support Oct 31, 2010
LICENSE Jeweler 1.5 Nov 26, 2010
README.rdoc added to the basic example to illustrate how serializing the session … May 25, 2011
Rakefile Gem updates; remove superfluous files from gem Sep 7, 2011


Ruby Dropbox Gem

An easy-to-use third-party interface to the RESTful Dropbox API.


gem install dropbox

Tutorial by Example

First things first: Be sure you've gotten a consumer key and secret from

# STEP 1: Authorize the user
session ='your_consumer_key', 'your_consumer_secret')
session.mode = :sandbox # might need to set this to :dropbox; consult your API account page
puts "Visit #{session.authorize_url} to log in to Dropbox. Hit enter when you have done this."

# STEP 2: Play!
session.upload('testfile.txt', '/')
uploaded_file = session.file('testfile.txt')
puts uploaded_file.metadata.size

uploaded_file.move 'new_name.txt'

# STEP 3: Save session for later'serialized_session.txt', 'w') do |f|
  f.puts session.serialize

# STEP 4: Play with saved session!
new_session = Dropbox::Session.deserialize('serialized_session.txt'))
account = new_session.account
puts account.display_name

Tutorial by Example, Rails Edition

A simple Rails controller that allows a user to first authorize their Dropbox account, and then upload a file to their Dropbox.

class DropboxController < ApplicationController
  def authorize
    if params[:oauth_token] then
      dropbox_session = Dropbox::Session.deserialize(session[:dropbox_session])
      session[:dropbox_session] = dropbox_session.serialize # re-serialize the authenticated session

      redirect_to :action => 'upload'
      dropbox_session ='your_consumer_key', 'your_consumer_secret')
      session[:dropbox_session] = dropbox_session.serialize
      redirect_to dropbox_session.authorize_url(:oauth_callback => url_for(:action => 'authorize'))

  def upload
    return redirect_to(:action => 'authorize') unless session[:dropbox_session]
    dropbox_session = Dropbox::Session.deserialize(session[:dropbox_session])
    return redirect_to(:action => 'authorize') unless dropbox_session.authorized?

    if request.method == :post then
      dropbox_session.upload params[:file], 'My Uploads'
      render :text => 'Uploaded OK'
      # display a multipart file field form

Features and Where to Find Them

  • Start with the Dropbox::Session class. The first thing you should do is authenticate your users and that class is how to do it.

  • The Dropbox::API module (attached to the Dropbox::Session class) is the meat and potatoes. Use it to modify a user's Dropbox.

  • The Dropbox::Entry class is a more object-oriented way of manipulating files. It's totally optional; check it out if you like OOP.

  • The Dropbox::Memoization module has some handy utility methods for memoizing server responses to reduce network calls. It's plug-in compatible with any caching strategy you might already have (memcache, etc.).

  • If you're using pingbacks, check out Dropbox::Event and Dropbox::Revision. Those classes parse pingbacks from Dropbox into Ruby objects.

Testing Your Code

The gem is fully specced. Run specs with +rake spec+. Before doing so, you will need to create a file called keys.json in the project root containing your Dropbox API key and secret, as well as the email and password for a Dropbox account. See the keys.json.example file to get started.

fguillen has implemented a mock of the Dropbox API server:

Note on Patches/Pull Requests

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don't break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.


Copyright © 2009 Tim Morgan. See LICENSE for details.