Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
An easy-to-use client library for the official Dropbox API.
tag: 1.2.3

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
examples
lib
spec
.document
.gitignore
.rspec
ChangeLog
Gemfile
Gemfile.lock
LICENSE
README.rdoc
Rakefile
VERSION
dropbox.gemspec
keys.json.example

README.rdoc

Ruby Dropbox Gem

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

Installation

gem install dropbox

Tutorial by Example

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

# STEP 1: Authorize the user
session = Dropbox::Session.new('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."
gets
session.authorize

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

uploaded_file.move 'new_name.txt'
uploaded_file.delete

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])
      dropbox_session.authorize(params)
      session[:dropbox_session] = dropbox_session.serialize # re-serialize the authenticated session

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

  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'
    else
      # display a multipart file field form
    end
  end
end

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: github.com/fguillen/DummyDropbox

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

Copyright © 2009 Tim Morgan. See LICENSE for details.

Something went wrong with that request. Please try again.