A Ruby client for the Dropbox REST API.
Goal:
To deliver a more Rubyesque experience when using the Dropbox API.
Current state:
First release, whole API covered.
From version 0.2.0, Dropbox::API::File#delete and Dropbox::API::Dir#delete are gone!!
The reason is that it's based on Hashie::Mash and was screwing Hash#delete.
It is replaced with Dropbox::API::File#destroy and Dropbox::API::Dir#destroy.
Dropbox::API is available on RubyGems, so:
gem install dropbox-api
Or in your Gemfile:
gem "dropbox-api"In order to use this client, you need to have an app created on https://www.dropbox.com/developers/apps.
Once you have it, put this configuration somewhere in your code, before you start working with the client.
Dropbox::API::Config.app_key = YOUR_APP_KEY
Dropbox::API::Config.app_secret = YOUR_APP_SECRET
Dropbox::API::Config.mode = "sandbox" # if you have a single-directory app
# Dropbox::API::Config.mode = "dropbox" # if your app has access to the whole dropboxThe client is the base for all communication with the API and wraps around almost all calls available in the API.
In order to create a Dropbox::API::Client object, you need to have the configuration set up for OAuth2. Second thing you need is to have the user authorize your app using OAuth2. Here's a short intro on how to do this:
consumer = ::Dropbox::API::OAuth2.consumer(:authorize)
authorize_uri = consumer.authorize_url(client_id: Dropbox::API::Config.app_key, response_type: 'code')
# Here the user goes to Dropbox, authorizes the app and is redirected, when
# they return, extract the &code query string parameter
consumer = ::Dropbox::API::OAuth2.consumer(:main)
access_token = consumer.auth_code.get_token(params[:code])Now that you have an authenticated OAuth2 access token, you can create a new instance of the Dropbox::API::Client, like this:
client = Dropbox::API::Client.new :token => access_token.tokenDropbox::API supplies you with a helper rake which will authorize a single client. This is useful for development and testing.
In order to have this rake available, put this on your Rakefile:
require "dropbox-api"
require "dropbox-api/tasks"
Dropbox::API::Tasks.installYou will notice that you have one new rake task - dropbox:authorize
When you call one of these Rake tasks, it will ask you to provide the app key and app secret. Afterwards it will present you with an authorize url on Dropbox.
Simply go to that url, authorize the app, then follow the instructions in the console.
The rake task will output valid ruby code which you can use to create a client.
A few things:
- It's using the ruby oauth2 gem, instead of reinventing the wheel and implementing OAuth2 communication
- It treats files and directories as Ruby objects with appropriate classes, on which you can perform operations
Consider the following example which takes all files with names like 'test.txt' and copies them with a suffix '.old'
This is how it would look using the SDK:
# Because you need the session with the right access token, you need to create one instance per user
@session = DropboxSession.new(APP_TOKEN, APP_SECRET)
@session.set_access_token(ACCESS_TOKEN, ACCESS_SECRET)
@client = DropboxClient.new(@session, :app_folder)
# The result is a hash, so we need to call a method on the client, supplying the right key from the hash
@client.search('/', 'test.txt').each do |hash|
@client.file_copy(hash['path'], hash['path'] + ".old")
endWith Dropbox::API, you can clean it up, first you put the app token and secret in a config or initializer file:
Dropbox::API::Config.app_key = APP_TOKEN
Dropbox::API::Config.app_secret = APP_SECRETAnd when you want to use it, just create a new client object with a specific access token and secret:
# The app token and secret are read from config, that's all you need to have a client ready for one user
@client = Dropbox::API::Client.new(:token => ACCESS_TOKEN, :secret => ACCESS_SECRET)
# The file is a Dropbox::API::File object, so you can call methods on it!
@client.search('test.txt').each do |file|
file.copy(file.path + ".old2")
endDropbox::API does not extend the Ruby primitives, like the dropbox gem:
https://github.com/RISCfuture/dropbox/tree/master/lib/dropbox/extensions
Returns a simple object with information about the account:
client.account # => #<Dropbox::API::Object>For more info, see https://www.dropbox.com/developers/reference/api#account-info
When provided a path, returns a single file or directory
client.find 'file.txt' # => #<Dropbox::API::File>Removes the file specified by path
Returns a Dropbox::API::File object of the deleted file
client.destroy 'file.txt' # => #<Dropbox::API::File>When provided a path, returns a list of files or directories within that path
By default it's the root path:
client.ls # => [#<Dropbox::API::File>, #<Dropbox::API::Dir>]But you can provide your own path:
client.ls 'somedir' # => [#<Dropbox::API::File>, #<Dropbox::API::Dir>]Creates a new directory and returns a Dropbox::API::Dir object
client.mkdir 'new_dir' # => #<Dropbox::API::Dir>Stores a file with a provided body under a provided name and returns a Dropbox::API::File object
client.upload 'file.txt', 'file body' # => #<Dropbox::API::File>Stores a file from a File object under a provided name and returns a Dropbox::API::File object. It should be used for larger files.
client.chunked_upload 'file.txt', File.open('file.txt') # => #<Dropbox::API::File>Downloads a file with a provided name and returns it's content
client.download 'file.txt' # => 'file body'When provided a pattern, returns a list of files or directories within that path
By default it searches the root path:
client.search 'pattern' # => [#<Dropbox::API::File>, #<Dropbox::API::Dir>]However, you can specify your own path:
client.search 'pattern', :path => 'somedir' # => [#<Dropbox::API::File>, #<Dropbox::API::Dir>]Returns a cursor and a list of files that have changed since the cursor was generated.
delta = client.delta 'abc123'
delta.cursor # => 'def456'
delta.entries # => [#<Dropbox::API::File>, #<Dropbox::API::Dir>]When called without a cursor, it returns all the files.
delta = client.delta 'abc123'
delta.cursor # => 'abc123'
delta.entries # => [#<Dropbox::API::File>, #<Dropbox::API::Dir>]Optionally, you can set additional parameters, e.g. path_prefix. You can find all available parameters in the Dropbox API documentation.
delta = client.delta 'abc123', path_prefix: '/Path/To/My/Folder'
delta.cursor # => 'abc123'
delta.entries # => [#<Dropbox::API::File>, #<Dropbox::API::Dir>]These methods are shared by Dropbox::API::File and Dropbox::API::Dir
Copies a file/directory to a new specified filename
file.copy 'newfilename.txt' # => #<Dropbox::API::File>Moves a file/directory to a new specified filename
file.move 'newfilename.txt' # => #<Dropbox::API::File>Deletes a file/directory
file.destroy 'newfilename.txt' # => #<Dropbox::API::File>Returns an Array of Dropbox::API::File objects with appropriate rev attribute
For more info, see https://www.dropbox.com/developers/reference/api#revisions
Restores a file to a specific revision
For more info, see https://www.dropbox.com/developers/reference/api#restore
Returns the link to a file page in Dropbox
For more info, see https://www.dropbox.com/developers/reference/api#shares
Returns the link to a file in Dropbox
For more info, see https://www.dropbox.com/developers/reference/api#media
Returns the thumbnail for an image
For more info, see https://www.dropbox.com/developers/reference/api#thumbnail
Downloads a file and returns it's content
file.download # => 'file body'Returns a list of files or directorys within that directory
dir.ls # => [#<Dropbox::API::File>, #<Dropbox::API::Dir>]In order to run tests, you need to have an application created and authorized. Put all tokens in spec/connection.yml and you're good to go.
Check out spec/connection.sample.yml for an example.
Copyright (c) 2011 Marcin Bunsch, Future Simple Inc. See LICENSE for details.