docs/index.html in dropbox_api-0.1.20 vs docs/index.html in dropbox_api-0.1.21
- old
+ new
@@ -114,46 +114,114 @@
<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>
+<p>The official documentation on the process to get an authorization code is
+<a href="https://developers.dropbox.com/es-es/oauth-guide#implementing-oauth">here</a>,
+it describes the two options listed below.</p>
<h4 id="option-a-get-your-access-token-from-the-website">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>For a quick test, you can obtain an access token from the App Console in
+<a href="https://www.dropbox.com/developers/">Dropbox's website</a>. Select from
+<em>My apps</em> your application, you may need to create one if you
+haven't done so yet. Under your application settings, find section
+<em>OAuth 2</em>, there is a button to generate an access token.</p>
-<p>Under your application settings, find section <em>OAuth 2</em>. You'll find a button
-to generate an access token.</p>
+<h4 id="option-b-oauth2-code-flow">Option B: OAuth2 Code Flow</h4>
-<h4 id="option-b-use-dropboxapi-authenticator">Option B: Use <code>DropboxApi::Authenticator</code></h4>
+<p>This is typically what you will use in production, you can obtain an
+authorization code with a 3-step process:</p>
-<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/..."
+<pre class="code ruby"><code class="ruby"><span class='comment'># 1. Get an authorization URL.
+</span><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_auth_code'>auth_code</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 class='comment'># 2. Log into Dropbox and authorize your app. You need to open the
+</span><span class='comment'># authorization URL in your browser.
</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>
+<span class='comment'># 3. Exchange the authorization code for a reusable access token (not visible
+</span><span class='comment'># to the user).
+</span><span class='id identifier rubyid_access_token'>access_token</span> <span class='op'>=</span> <span class='id identifier rubyid_authenticator'>authenticator</span><span class='period'>.</span><span class='id identifier rubyid_auth_code'>auth_code</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_access_token'>access_token</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><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='label'>access_token:</span> <span class='id identifier rubyid_access_token'>access_token</span><span class='rparen'>)</span>
-<h4 id="standard-oauth-2-flow">Standard OAuth 2 flow</h4>
+<span class='comment'># For backwards compatibility, the following also works:
+</span><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='id identifier rubyid_access_token'>access_token</span><span class='period'>.</span><span class='id identifier rubyid_token'>token</span><span class='rparen'>)</span>
+</code></pre>
-<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>
+<h5 id="integration-with-rails">Integration with Rails</h5>
<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>
+<h5 id="using-refresh-tokens">Using refresh tokens</h5>
+
+<p>Access tokens are short-lived by default (as of September 30th, 2021),
+applications that require long-lived access to the API without additional
+interaction with the user should use refresh tokens.</p>
+
+<p>The process is similar but a token refresh might seamlessly occur as you
+perform API calls. When this happens you'll need to store the
+new token hash if you want to continue using this session, you can use the
+<code>on_token_refreshed</code> callback to do this.</p>
+
+<pre class="code ruby"><code class="ruby"><span class='comment'># 1. Get an authorization URL, requesting offline access type.
+</span><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_auth_code'>auth_code</span><span class='period'>.</span><span class='id identifier rubyid_authorize_url'>authorize_url</span><span class='lparen'>(</span><span class='label'>token_access_type:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>offline</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span>
+
+<span class='comment'># 2. Log into Dropbox and authorize your app. You need to open the
+</span><span class='comment'># authorization URL in your browser.
+</span>
+<span class='comment'># 3. Exchange the authorization code for a reusable access token
+</span><span class='id identifier rubyid_access_token'>access_token</span> <span class='op'>=</span> <span class='id identifier rubyid_authenticator'>authenticator</span><span class='period'>.</span><span class='id identifier rubyid_auth_code'>auth_code</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='comment'># You can now use the access token to initialize a DropboxApi::Client, you
+</span><span class='comment'># should also provide a callback function to store the updated access token
+</span><span class='comment'># whenever it's refreshed.
+</span><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='label'>access_token:</span> <span class='id identifier rubyid_access_token'>access_token</span><span class='comma'>,</span>
+ <span class='label'>on_token_refreshed:</span> <span class='id identifier rubyid_lambda'>lambda</span> <span class='lbrace'>{</span> <span class='op'>|</span><span class='id identifier rubyid_new_token_hash'>new_token_hash</span><span class='op'>|</span>
+ <span class='comment'># token_hash is a serializable Hash, something like this:
+</span> <span class='comment'># {
+</span> <span class='comment'># "uid"=>"440",
+</span> <span class='comment'># "token_type"=>"bearer",
+</span> <span class='comment'># "scope"=>"account_info.read account_info.write...",
+</span> <span class='comment'># "account_id"=>"dbid:AABOLtA1rT6rRK4vajKZ...",
+</span> <span class='comment'># :access_token=>"sl.A5Ez_CBsqJILhDawHlmXSoZEhLZ4nuLFVRs6AJ...",
+</span> <span class='comment'># :refresh_token=>"iMg4Me_oKYUAAAAAAAAAAapQixCgwfXOxuubCuK_...",
+</span> <span class='comment'># :expires_at=>1632948328
+</span> <span class='comment'># }
+</span> <span class='const'>SomewhereSafe</span><span class='period'>.</span><span class='id identifier rubyid_save'>save</span><span class='lparen'>(</span><span class='id identifier rubyid_new_token_hash'>new_token_hash</span><span class='rparen'>)</span>
+ <span class='rbrace'>}</span>
+<span class='rparen'>)</span>
+</code></pre>
+
+<p>Once you've gone through the process above, you can skip the steps that require
+user interaction in subsequent initializations of <code>DropboxApi::Client</code>. For
+example:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='comment'># 1. Initialize an authenticator
+</span><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='comment'># 2. Retrieve the token hash you previously stored somewhere safe, you can use
+</span><span class='comment'># it to build a new access token.
+</span><span class='id identifier rubyid_access_token'>access_token</span> <span class='op'>=</span> <span class='const'>OAuth2</span><span class='op'>::</span><span class='const'>AccessToken</span><span class='period'>.</span><span class='id identifier rubyid_from_hash'>from_hash</span><span class='lparen'>(</span><span class='id identifier rubyid_authenticator'>authenticator</span><span class='comma'>,</span> <span class='id identifier rubyid_token_hash'>token_hash</span><span class='rparen'>)</span>
+
+<span class='comment'># 3. You now have an access token, so you can initialize a client like you
+</span><span class='comment'># would normally:
+</span><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='label'>access_token:</span> <span class='id identifier rubyid_access_token'>access_token</span><span class='comma'>,</span>
+ <span class='label'>on_token_refreshed:</span> <span class='id identifier rubyid_lambda'>lambda</span> <span class='lbrace'>{</span> <span class='op'>|</span><span class='id identifier rubyid_new_token_hash'>new_token_hash</span><span class='op'>|</span>
+ <span class='const'>SomewhereSafe</span><span class='period'>.</span><span class='id identifier rubyid_save'>save</span><span class='lparen'>(</span><span class='id identifier rubyid_new_token_hash'>new_token_hash</span><span class='rparen'>)</span>
+ <span class='rbrace'>}</span>
+<span class='rparen'>)</span>
+</code></pre>
+
<h3 id="performing-api-calls">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>
@@ -192,10 +260,28 @@
<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>
+<h3 id="accessing-team-folders">Accessing Team Folders</h3>
+
+<p>In order to access your team scope you need to add the namespace_id to you request headers.
+This can be done using the middlewere layer as per the below:</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='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_namespace_id'>namespace_id</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_get_current_account'>get_current_account</span><span class='period'>.</span><span class='id identifier rubyid_root_info'>root_info</span><span class='period'>.</span><span class='id identifier rubyid_root_namespace_id'>root_namespace_id</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='lparen'>(</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span>
+<span class='comment'>#=> Now returns the team folders
+</span></code></pre>
+
+<p>You could unset the namespace ID at any point afterwards with just:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_namespace_id'>namespace_id</span> <span class='op'>=</span> <span class='kw'>nil</span>
+</code></pre>
+
<h2 id="dependencies">Dependencies</h2>
<p>This gem depends on
<a href="https://github.com/oauth-xx/oauth2">oauth2</a>
and
@@ -250,12 +336,12 @@
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 Sun Feb 7 11:51:54 2021 by
+ Generated on Wed Sep 29 23:44:24 2021 by
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
- 0.9.26 (ruby-2.5.1).
+ 0.9.26 (ruby-2.6.5).
</div>
</div>
</body>
</html>
\ No newline at end of file