<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>
File: README
— Documentation by YARD 0.9.15
</title>
<link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
<script type="text/javascript" charset="utf-8">
pathId = "README";
relpath = '';
</script>
<script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
<script type="text/javascript" charset="utf-8" src="js/app.js"></script>
</head>
<body>
<div class="nav_wrap">
<iframe id="nav" src="class_list.html?1"></iframe>
<div id="resizer"></div>
</div>
<div id="main" tabindex="-1">
<div id="header">
<div id="menu">
<a href="_index.html">Index</a> »
<span class="title">File: README</span>
</div>
<div id="search">
<a class="full_list_link" id="class_list_link"
href="class_list.html">
<svg width="24" height="24">
<rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
<rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
<rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
</svg>
</a>
</div>
<div class="clear"></div>
</div>
<div id="content"><div id='filecontents'><h1>DropboxApi</h1>
<p>Library for communicating with Dropbox API v2.</p>
<h2>Installation</h2>
<p>Add this line to your application's Gemfile:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>dropbox_api</span><span class='tstring_end'>'</span></span>
</code></pre>
<p>And then execute:</p>
<pre class="code ruby"><code class="ruby">$ bundle
</code></pre>
<p>Or install it yourself as:</p>
<pre class="code ruby"><code class="ruby">$ gem install dropbox_api
</code></pre>
<h2>Documentation</h2>
<p>Please, refer to this gem's custom <a href="http://jesus.github.io/dropbox_api">Dropbox API
documentation</a>.
Most of the time you'll be checking the <a href="http://jesus.github.io/dropbox_api/DropboxApi/Client.html">available
endpoints</a>.</p>
<p>Unfortunately, the documentation at <a href="http://www.rubydoc.info">RubyDoc.info</a> is
disrecommended because it lacks some nice features that have been added with
YARD plugins:</p>
<ul>
<li>Each endpoint includes its tests right below the description, this works as
an example of its usage.</li>
<li>All endpoints are shown as methods of the <code>Client</code> class, just as you will
use them.</li>
</ul>
<h2>Basic set up</h2>
<h3>Authorize your application</h3>
<p>Dropbox uses OAuth, in order to use this library from your application you'll
have to get an authorization code.</p>
<p>Once you have it, just pass it on client initialization:</p>
<pre class="code ruby"><code class="ruby"><span class='const'><span class='object_link'><a href="DropboxApi.html" title="DropboxApi (module)">DropboxApi</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="DropboxApi/Client.html" title="DropboxApi::Client (class)">Client</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="DropboxApi/Client.html#initialize-instance_method" title="DropboxApi::Client#initialize (method)">new</a></span></span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>VofXAX8D...</span><span class='tstring_end'>"</span></span><span class='rparen'>)</span>
<span class='comment'>#=> #<DropboxApi::Client ...>
</span></code></pre>
<p>Or set it as an ENV variable called <code>DROPBOX_OAUTH_BEARER</code>, for example:</p>
<pre class="code ruby"><code class="ruby"><span class='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>DROPBOX_OAUTH_BEARER</span><span class='tstring_end'>"</span></span><span class='rbracket'>]</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>VofXAX8D...</span><span class='tstring_end'>"</span></span>
<span class='const'><span class='object_link'><a href="DropboxApi.html" title="DropboxApi (module)">DropboxApi</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="DropboxApi/Client.html" title="DropboxApi::Client (class)">Client</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="DropboxApi/Client.html#initialize-instance_method" title="DropboxApi::Client#initialize (method)">new</a></span></span>
<span class='comment'>#=> #<DropboxApi::Client ...>
</span></code></pre>
<p>Note that setting an ENV variable is only a feasible choice if you're only
using one account.</p>
<h4>Option A: Get your access token from the website</h4>
<p>The easiest way to obtain an access token is to get it from the Dropbox website.
You just need to log in to Dropbox and refer to the <em>developers</em> section, go to
<em>My apps</em> and select your application, you may need to create one if you
haven't done so yet.</p>
<p>Under your application settings, find section <em>OAuth 2</em>. You'll find a button
to generate an access token.</p>
<h4>Option B: Use <code>DropboxApi::Authenticator</code></h4>
<p>You can obtain an authorization code with this library:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_authenticator'>authenticator</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="DropboxApi.html" title="DropboxApi (module)">DropboxApi</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="DropboxApi/Authenticator.html" title="DropboxApi::Authenticator (class)">Authenticator</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="DropboxApi/Authenticator.html#initialize-instance_method" title="DropboxApi::Authenticator#initialize (method)">new</a></span></span><span class='lparen'>(</span><span class='const'>CLIENT_ID</span><span class='comma'>,</span> <span class='const'>CLIENT_SECRET</span><span class='rparen'>)</span>
<span class='id identifier rubyid_authenticator'>authenticator</span><span class='period'>.</span><span class='id identifier rubyid_authorize_url'>authorize_url</span> <span class='comment'>#=> "https://www.dropbox.com/..."
</span>
<span class='comment'># Now you need to open the authorization URL in your browser,
</span><span class='comment'># authorize the application and copy your code.
</span>
<span class='id identifier rubyid_auth_bearer'>auth_bearer</span> <span class='op'>=</span> <span class='id identifier rubyid_authenticator'>authenticator</span><span class='period'>.</span><span class='id identifier rubyid_get_token'>get_token</span><span class='lparen'>(</span><span class='const'>CODE</span><span class='rparen'>)</span> <span class='comment'>#=> #<OAuth2::AccessToken ...>`
</span><span class='id identifier rubyid_auth_bearer'>auth_bearer</span><span class='period'>.</span><span class='id identifier rubyid_token'>token</span> <span class='comment'>#=> "VofXAX8D..."
</span><span class='comment'># Keep this token, you'll need it to initialize a `DropboxApi::Client` object
</span></code></pre>
<h4>Standard OAuth 2 flow</h4>
<p>This is what many web applications will use. The process is described in
Dropbox's <a href="https://www.dropbox.com/developers/reference/oauth-guide#oauth-2-on-the-web">OAuth guide</a>.</p>
<p>If you have a Rails application, you might be interested in this <a href="http://jesus.github.io/dropbox_api/file.rails_setup.html">setup
guide</a>.</p>
<h3>Performing API calls</h3>
<p>Once you've initialized a client, for example:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="DropboxApi.html" title="DropboxApi (module)">DropboxApi</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="DropboxApi/Client.html" title="DropboxApi::Client (class)">Client</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="DropboxApi/Client.html#initialize-instance_method" title="DropboxApi::Client#initialize (method)">new</a></span></span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>VofXAX8D...</span><span class='tstring_end'>"</span></span><span class='rparen'>)</span>
<span class='comment'>#=> #<DropboxApi::Client ...>
</span></code></pre>
<p>You can perform an API call like this:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_result'>result</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_list_folder'>list_folder</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>/sample_folder</span><span class='tstring_end'>"</span></span>
<span class='comment'>#=> #<DropboxApi::Results::ListFolderResult>
</span><span class='id identifier rubyid_result'>result</span><span class='period'>.</span><span class='id identifier rubyid_entries'>entries</span>
<span class='comment'>#=> [#<DropboxApi::Metadata::Folder>, #<DropboxApi::Metadata::File>]
</span><span class='id identifier rubyid_result'>result</span><span class='period'>.</span><span class='id identifier rubyid_has_more?'>has_more?</span>
<span class='comment'>#=> false
</span></code></pre>
<p>The instance of <code>Client</code> we've initialized is the one you'll be using to
perform API calls. You can check the class' documentation to find
<a href="http://jesus.github.io/dropbox_api/DropboxApi/Client.html">all available endpoints</a>.</p>
<h3>Large file uploads</h3>
<p>If you need to upload files larger than 150MB the default <code>#upload</code> endpoint
won't work. Instead, you need to start a upload session and upload
the file in small chunks.</p>
<p>To make this easier, the method <code>upload_by_chunks</code> will handle this for you,
example:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="DropboxApi.html" title="DropboxApi (module)">DropboxApi</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="DropboxApi/Client.html" title="DropboxApi::Client (class)">Client</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="DropboxApi/Client.html#initialize-instance_method" title="DropboxApi::Client#initialize (method)">new</a></span></span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>VofXAX8D...</span><span class='tstring_end'>"</span></span><span class='rparen'>)</span>
<span class='comment'>#=> #<DropboxApi::Client ...>
</span><span class='const'>File</span><span class='period'>.</span><span class='id identifier rubyid_open'>open</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>large_file.avi</span><span class='tstring_end'>"</span></span><span class='rparen'>)</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_f'>f</span><span class='op'>|</span>
<span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_upload_by_chunks'>upload_by_chunks</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>/remote_path.txt</span><span class='tstring_end'>"</span></span><span class='comma'>,</span> <span class='id identifier rubyid_f'>f</span>
<span class='kw'>end</span>
</code></pre>
<p>Check out the
<a href="http://www.xuuso.com/dropbox_api/DropboxApi/Client.html#upload_by_chunks-instance_method">method documentation</a>
to find out all available options.</p>
<h2>Dependencies</h2>
<p>This gem depends on
<a href="https://github.com/oauth-xx/oauth2">oauth2</a>
and
<a href="https://github.com/lostisland/faraday">faraday</a>.</p>
<p>It has official support for Ruby versions <code>1.9.x</code> and <code>2.x</code>.</p>
<h2>Development</h2>
<p>After checking out the repo, run <code>bin/setup</code> to install dependencies. Then, run
<code>bin/console</code> for an interactive prompt that will allow you to experiment.</p>
<h3>Testing</h3>
<p>I recommend you to use a test account other than your main one.</p>
<p>We use VCR to record the HTTP calls to Dropbox, however we sometimes need to
regenerate the cassettes. Let's take <code>list_folder</code> as an example to show what
would be the procedure to do so:</p>
<ol>
<li><p>Manually delete the existing cassettes in
<code>spec/fixtures/vcr_cassettes/list_folder/*.yml</code>.</p></li>
<li><p>Run the task to build the scaffolding in your Dropbox account so the tests
will pass. If it doesn't exist you may need to write it yourself, check
the <code>DropboxScaffoldBuilder</code> class to find all existing scaffold builders.</p>
<pre class="code text"><code class="text">DROPBOX_OAUTH_BEARER=YOUR_AUTH_BEARER rake test:build_scaffold[list_folder]
</code></pre></li>
<li><p>Run the tests and the cassettes will be written:</p>
<pre class="code text"><code class="text">DROPBOX_OAUTH_BEARER=YOUR_AUTH_BEARER rspec spec/endpoints/files/list_folder_spec.rb
</code></pre></li>
</ol>
<p>The OAuth bearer shouldn't have been recorded in the cassette and it should've
been filtered. However, you may want to double check before pushing your
updates to Github.</p>
<p>Tip: You can simply run <code>export DROPBOX_OAUTH_BEARER=YOUR_AUTH_BEARER</code> at
the beginning of your work session so you don't need to prefix it in every
command line.</p>
<h2>Contributing</h2>
<p>Any help will be much appreciated. The easiest way to help is to implement one
or more of the <a href="http://jesus.github.io/dropbox_api/file.api_coverage.html">endpoints that are still pending</a>. To see how the
endpoints are implemented, check out the <code>lib/dropbox_api/endpoints</code> folder.</p>
</div></div>
<div id="footer">
Generated on Fri Nov 16 09:02:01 2018 by
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
0.9.15 (ruby-2.3.3).
</div>
</div>
</body>
</html>