README.md

Why Not Amazon S3?

Cost Considerations: Even if S3 is more suitable for programming, keep in mind that increased operations may lead to higher costs. Amazon charges per API request, and high volumes of upload operations will raise your expenses.

Dropbox doesn't charges per API call, but manages rate-limit for API calls.

The my-dropbox-api handles the files uploading asyncroniously to meet with such a rate-limit, and keep your costs low at the same time!

THIS LIBRARY IS UNDER CONSTRUCTION

my-dropbox-api

The my-dropbox-api is a Ruby gem for managing DropBox uploading, downloading and sharing DropBox files and folders.

The main goals of building this gem are:

1. Simulate a permanent access token, since Dropbox is moving to "short-term live access codes";

2. Manage DropBox as an elastic-storage providers for our SaaS projects, allowing us to upload, download and share download links to files;

3. Backup and restore secret files of our projects that cannot be commited into the source code repository (E.g.: database passwords, SSL certificates, private keys).

1. Getting DropBox Refresh Token

1. Open a new browser, and login to your DropBox account.

2. In the same browser, go to this link: https://www.dropbox.com/oauth2/authorize?client_id=lnystcoayzse5at&token_access_type=offline&response_type=code

3. Follow the steps, and copy the "Access Code" to your clipboard.

4. Since Dropbox's "Access Codes" are short-term lived, you need to generate a "Refresh Token". We have published a helper page where you can get such a Refresh Token: https://connectionsphere.com/developers/dss

Note that you have to signup to ConnectionSphere to access this screen.

After you have performed these steps, you can find a new /Apps/mysaas-backups, as is shown in the picture below.

All the files and folders managed by my-dropbox-api will be scoped to that folder.

2. Getting ConnectionSphere API Key

1. Signup to ConnectionSphere here.

2. Get your API-KEY here.

3. Getting Started

Install my-dropbox-api gem.

gem install my-dropbox-api

Setup my-dropbox-api to access DropBox account.

requires 'my-dropbox-api'

BlackStack::DropBox.set({
    :vymeco_api_key => '118f3c32-c920-******',
    :dropbox_refresh_token => 'dh4UcV4dFVs******',
})

4. Creating Folders

# Create a folder
puts BlackStack::DropBox.dropbox_create_folder('/my-first-folder')
# => {"metadata": {"name": "my-first-folder", "path_lower": "/my-first-folder", "path_display": "/my-first-folder", "id": "id:Vtyvsunm9sMAAAAAAAAACA"}}

# Create a sub-folder
puts BlackStack::DropBox.dropbox_create_folder('/my-first-folder/my-first-sub-folder')
# => {"metadata": {"name": "my-first-sub-folder", "path_lower": "/my-first-folder/my-first-sub-folder", "path_display": "/my-first-folder/my-first-sub-folder", "id": "id:Vtyvsunm9sMAAAAAAAAACQ"}}

5. Uploading Files

# Create a local folder

# Create a local file
File.open('/tmp/my-first-file.txt', 'w') { |file| file.write('Hello World!') }

# Upload file
puts BlackStack::DropBox.dropbox_upload_file('/tmp/my-first-file.txt', '/my-first-folder/my-first-file.txt')
# => {"name": "my-first-file.txt", "path_lower": "/my-first-folder/my-first-file.txt", "path_display": "/my-first-folder/my-first-file.txt", "id": "id:Vtyvsunm9sMAAAAAAAAACw", "client_modified": "2023-03-25T14:20:36Z", "server_modified": "2023-03-25T14:20:37Z", "rev": "5f7ba36b1776ce01d7d61", "size": 12, "is_downloadable": true, "content_hash": "61f417374f4400b47dcae1a8f402d4f4dacf455a0442a06aa455a447b0d4e170"}

6. Uploading Folder Structures

Use BlackStack::DropBox.upload if you want to upload a folder, with all its sub-folders and files, recusivelly.

This method returns an array with a hash descritor of each operation performed.

# Create a local folder
Dir.mkdir('/tmp/my-second-folder')

# Ceate a local sub-folder
Dir.mkdir('/tmp/my-second-folder/my-second-sub-folder')

# Create a local file into the sub-folder
File.open('/tmp/my-second-folder/my-second-sub-folder/my-second-file.txt', 'w') { |file| file.write('Hello World!') }

# Upload file
ret = BlackStack::DropBox.upload('/tmp/my-second-folder', '/')
puts ret.join("\n")
# => {:file=>"my-second-folder", :type=>"folder", :result=>"{\"metadata\": {\"name\": \"my-second-folder\", \"path_lower\": \"/my-second-folder\", \"path_display\": \"/my-second-folder\", \"id\": \"id:Vtyvsunm9sMAAAAAAAAAEQ\"}}"}
# => {:file=>"my-second-sub-folder", :type=>"folder", :result=>"{\"metadata\": {\"name\": \"my-second-sub-folder\", \"path_lower\": \"/my-second-folder/my-second-sub-folder\", \"path_display\": \"/my-second-folder/my-second-sub-folder\", \"id\": \"id:Vtyvsunm9sMAAAAAAAAAEg\"}}"}
# => {:file=>"my-second-file.txt", :type=>"file", :result=>"{\"name\": \"my-second-file.txt\", \"path_lower\": \"/my-second-folder/my-second-sub-folder/my-second-file.txt\", \"path_display\": \"/my-second-folder/my-second-sub-folder/my-second-file.txt\", \"id\": \"id:Vtyvsunm9sMAAAAAAAAAEw\", \"client_modified\": \"2023-03-25T15:17:28Z\", \"server_modified\": \"2023-03-25T15:17:28Z\", \"rev\": \"5f7bb020690c7e01d7d61\", \"size\": 12, \"is_downloadable\": true, \"content_hash\": \"61f417374f4400b47dcae1a8f402d4f4dacf455a0442a06aa455a447b0d4e170\"}"}

7. Getting Download Link of a File

# Get download link for a file
puts BlackStack::DropBox.get_file_url('/.pages/383ff473-b649-4cf0-9090-a41022c8d6c4.html')
# => https://dl.dropboxusercontent.com/s/9bgveh24fm89v4i/my-first-file.txt?dl=1

8. Advanced: Managing Secret Files of Your Project

(WARNING: This section is pending of documentation)

9. Advanced: Creating Your Own DropbBox App.

(WARNING: This section has not been tested yet)

If you want to register your own DropBox APP, instead to use ConnectionSphere, follow the steps below:

1. Signup to DropBox here or login to an existing account here.

2. Go to your DropBox's account home here, and double-check you are logged into.

3. Go to DropBox Developers Center.

4. Click on the "Create app" button.

5. In the step 1 (Choose an API), choose "Scoped access".

6. In the step 2 (Choose the type of access you need), choose "App folder".

7. In the step 3 (Name your app), write "mysaas-backup".

8. Agree with the "Dropbox API Terms and Conditions", and click on "Create app".

You will be redirected to your new app's configuration page. If you didn't, just go to https://www.dropbox.com/developers/apps in your browser.

Now, you have to setup your app's permissions.

9. Click on the "Permissions" tab.

10. Check the "files.metadata.write", "files.content.write" and "files.content.read" options.

11. Scroll down and click on "Submit".

Finally, you have to grab your API key.

12. In the same screen, go to the "Settings".

13. Scroll down click on "Generate access token".

14. Grab the DropBox App Key and DropBox App Secret and add them to your configuration.

BlackStack::DropBox.set({
    :dropbox_refresh_token => '<past your access token here>',
    # if you are using your own DropBox App
    :dropbox_app_key => '....',
    :dropbox_app_secret => '....'
})