Using a Dropbox Datastore

Important: DropBox announced on April 23, 2015 that this API is deprecated and will be phased out by April, 2016.

It's easy to save and read record based data on Dropbox using AppStudio using Dropbox Datastores. You can then access them on all your devices and on your desktop.

• Apps must be set up in Dropbox before they will run.
• Apps need to be deployed. They cannot run locally.
• Your site will need a signing certificate so OAuth will work.
• You can only run someone else's app if you have their permission.
• Therefore you can only access someone else's files with their permission.
• If you want to access files directly, use Dropbox Files.
• Maximum datastore size is 10 megs.
• Maximum records per datastore is 100,000.
• Maximum record size is 100k.
• The first 5 megs do not subtract from your Dropbox allocation.

Here's how:

Get a Dropbox account.

Use your existing account or get a new one. They're free and easy to set up.

Create your app in the Dropbox App Console

Go to Dropbox App Console and create a Dropbox API app, that does "Datastores only".

Settings

Settings Fields:

• Status: Development allows up to 100 users. To apply for Production, your app will have to approved by Dropbox.
• Development users: Who is allowed to use the app?
• Permission type: Normally, read and write to its own folder.
• App key, App secret: Generated by Dropbox. Use App key in your app to identify the Dropbox app.
• OAuth redirect URIs: The complete URL to your deployed app.
• Drop-ins domains: Not needed.
• Datastores: Not needed.

Details

Details Fields:

• App name: The name of your app. Don't use "Dropbox" in the name.
• Publisher: Your name or the name of your company.
• Description: A description of your app.
• App website: The main website for your app.
• App icons: 64x64 and 256x256 images. You need to save them to your Dropbox before uploading them.

Write your app

Add the Dropbox library to your project

Select Global Code and Project Properties in the Project Explorer, and add the Dropbox library to the project:

Log into Dropbox

Security is important to Dropbox apps. Before you can do anything, you need to login. Dropbox uses a security schema call OAuth, which is fairly ease to use. OAuth requires that you use https: your site site will need a signing certificate. You can install a self signed certificate (browsers will complain) or an official one (about $59/year from a certificate authority).

Here is what you do at the start of your app:

Dim APP_KEY = "qx65sf9nruudj73"
Dim client = new Dropbox.Client({key: APP_KEY})
client.authenticate({interactive:False}, authenticationError)

Function authenticationError(err)
  If err Then MsgBox "Dropbox Authentication error: " & err
End Function

Once this is done, you can check to see if the user is authorized. If not, you need to authenticate:

client.authenticate()

This will load the Dropbox web page, ask the user to log in if needed and get authorization for the app.

Initialize your Table

Once authenticated, you need open the datastore for the app.

  datastoreManager = client.getDatastoreManager()
  datastoreManager.openDefaultDatastore(openDataStoreComplete)

Function openDataStoreComplete(err, datastore)
  If err Then 
    MsgBox "Error opening datastore: " & err
  Else
    studentTable=datastore.getTable("students")
  End If
End Function

• This app uses only the default datastore.
• It has one table called studentTable.
• A datastore can have multiple tables.
• getTable() returns the table.
• A table is created when records are added to it.

Save a record

Adding records to a table is easy.

  data = {name: txtName.value, age: TxtAge.value}
  ref = studentTable.insert(data)

• The record is simply added.
• A reference to the record is returned.
• There is no duplicate checking.
• The data is formatted as an object.
• Since the operation updates a local file, there is no need for an asynchronous callback.
• Dropbox will take care of synching the updated datastore to its server later.

Find a record

The Dropbox query() function is a database style lookup.

  results = studentTable.query({name: txtFind.value})
  If Len(results)>0 Then
    MsgBox results[0].get("name") & " is " & results[0].get("age")
  Else
    MsgBox "Not found"
  End If

• The query function takes an object as a parameter.
• It can use one or more name,value pairs to match up with.
• An array is returned with all the matching records.
• Each element of the array is a reference to the record.
• Use the get() function to get fields in a record.
• Use the set() function to change fields in a record.

Delete a record

Deletes a record from a datastore.

  If Len(results)>0 Then 
    results[0].deleteRecord()
    MsgBox "Deleted"
  End If

• You need the reference to the record to delete it.
• Operation happens immediately to the local copy of the datastore.
• Dropbox will synch to its servers later.

Examining a datastore on Dropbox

You can look at your datastore on Dropbox.com. Go to the App Console and choose Browse DataStores.

You can then choose the app you are interested in and browse its datastore:

Other Dropbox Datastore functions

Here is the full list of calls that can be made to the Dropbox client. Docs are here.

Class Methods

• int64(x)
• isInt64(x)
• isValidID(datastoreId)

Instance Methods

• getTable(tableId)
• ListTableIds()
• close()
• getId()
• getSyncStatus()

Instance Properties

• recordsChanged (Dropbox.Util.EventSource<Dropbox.Datastore.RecordsChanged>)
• syncStatusChanged (Dropbox.Util.EventSource<?>)

Datastore Manager

• close()
• openDefaultDatastore(callback)
• openDatastore(datastoreId, callback)
• createDatastore(callback)
• deleteDatastore(datastoreId, callback)
• listDatastores(callback)

Datastore Properties

• datastoreListChanged (Dropbox.Util.EventSource<Dropbox.Datastore.DatastoreListChanged>)
• getId()
• getDatastoreInfos()

Table Methods

• isValidId(tableId)
• getId()
• get(recordId)
• getOrInsert(recordId, defaultValues)
• insert(fieldValues)
• query(fieldValues)
• setResolutionRule(fieldName, rule)

Record Methods

• isValidId(recordId)
• get(fieldName)
• set(fieldName, value)
• getOrCreateList(fieldName)
• getFields()
• update(a)
• deleteRecord()
• has(fieldName)
• getId()
• getTable()
• isDeleted()
• affectedRecordsByTable()
• affectedRecordsForTable(tableId)
• isLocal()

Check full docs - lots more stuff!

"Dropbox Cannot Authenticate" message

If your app should get a message like this after working for a little while, you may need to clean the cache on your computer or device. This is more likely to happen during development than in released apps.