Ruby Dropbox Gem

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

Installation

geminstalldropbox

Tutorial by Example

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

# STEP 1: Authorize the usersession = Dropbox::Session.new('your_consumer_key', 'your_consumer_secret')
session.mode = :sandbox# might need to set this to :dropbox; consult your API account pageputs"Visit #{session.authorize_url} to log in to Dropbox. Hit enter when you have done this."getssession.authorize# STEP 2: Play!session.upload('testfile.txt', '/')
uploaded_file = session.file('testfile.txt')
putsuploaded_file.metadata.sizeuploaded_file.move'new_name.txt'uploaded_file.delete# STEP 3: Save session for laterFile.open('serialized_session.txt', 'w') do|f|f.putssession.serializeend# STEP 4: Play with saved session!new_session = Dropbox::Session.deserialize(File.read('serialized_session.txt'))
account = new_session.accountputsaccount.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.

classDropboxController<ApplicationControllerdefauthorizeifparams[:oauth_token] thendropbox_session = Dropbox::Session.deserialize(session[:dropbox_session])
dropbox_session.authorize(params)
session[:dropbox_session] = dropbox_session.serialize# re-serialize the authenticated sessionredirect_to:action=>'upload'elsedropbox_session = Dropbox::Session.new('your_consumer_key', 'your_consumer_secret')
session[:dropbox_session] = dropbox_session.serializeredirect_todropbox_session.authorize_url(:oauth_callback=>url_for(:action=>'authorize'))
endenddefuploadreturnredirect_to(:action=>'authorize') unlesssession[:dropbox_session]
dropbox_session = Dropbox::Session.deserialize(session[:dropbox_session])
returnredirect_to(:action=>'authorize') unlessdropbox_session.authorized?ifrequest.method==:postthendropbox_session.uploadparams[:file], 'My Uploads'render:text=>'Uploaded OK'else# display a multipart file field formendendend

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.