Get Started with the Dropbox SDK

Using the Dropbox SDK

The Dropbox SDK uses the Core API which exposes the fundamental building blocks that make up Dropbox. It's based on HTTP and OAuth, so it should be very familiar to most developers.

You can get the Dropbox SDK here.

If you want to follow along, first register a new app on the App Console to get an App Key and App Key Secret. You'll need these app keys to use the SDK.

Save the SDK as Class DBox.ahk, either in the same folder as your project or in one of the standard libraries. Include the SDK in your script using one of the following statements:

#Include Class DBox.ahk ; If the SDK is in the same folder as your project
#Include <Class DBox> ; If the SDK is in one of the standard libraries

Authenticating your app

The Core API uses OAuth v1, but the SDK will take care of most of it so you don't have to start from scratch.

You'll need to provide your app key and secret as well as the access level, you selected when creating the app.

Pass all three values to the new operator:

MyDB := new DBox("wysh39uunwovz6", "z8u4w3lr1zswro", "dropbox")

Now we're all set to start the OAuth flow. The OAuth flow has three parts:

Get a request token.
Ask the user to authorize linking your app to their Dropbox account.
Once authorized, exchange the request token for an access token, which will be used for calling the Core API.

We'll start by using the MyDBox object to get a request tokens via the GetAuthorizationTokens() method.

MyDB.GetAuthorizationTokens()

This will add the OauthToken and OauthTokenSecret members to the MyDB object. These are used in the next authorization step.

Now that you have the request tokens, you can ask the user to authorize your app. To do this you have two choices:

open https://www2.dropbox...ze?oauth_token=" this.OauthToken and have the user authorize manually.
Use the GetUserAuthorization(UserEmail, UserPassword) for a more automated approach.

This step asks the user to grant your app access to their Dropbox with the permissions you specified when creating your app.

Once the user has granted permission to your app, we can upgrade the now-authorized request token to an access token. We'll do that by using the GetAccessTokens() method.

; This will fail if the user didn't visit the above URL and hit 'Allow'
MyDB.GetAccessTokens()

This will replace the values for OauthToken and OauthTokenSecret with true access tokens.

These access tokens are all you'll need to make API requests on behalf of this user, so you should store them away for safe-keeping (even though we don't for this tutorial). By storing the access tokens, you won't need to go through these steps again unless the user reinstalls your app or you revoke access via the Dropbox website. Just pass the access keys as the last two parameters of the new operator:

MyDB := new DBox("wysh39duunwovz6", "z8u4w3alr1zswro", "dropbox", "df7sdfsd8g7df7", "jh34jh34h45j")

Those five parameters are what you need to save.

Now the hard part is done and you have all you need to use the SDK. To test that we've got access to the Core API, try calling:

GetAccountInfo(Locale := "en")

which will return an object containing information about the user's linked account:

AccountInfo := MyDB.GetAccountInfo()
MsgBox % AccountInfo.email

If you've made it this far, you have a simple app that uses the Core API to link to a Dropbox account and your first API call for account info. Next, we'll upload a file to Dropbox, get its metadata, and then download it back to our app.

Uploading files

Let's say we're building a text editing app and we want to use it to save your latest magnum opus to Dropbox. Let's browse the methods in the SDK to see which one will do that for us. All of the available methods are listed a the top of the source of the SDK. Looking there you should find:

PutFile() - Uploads a file.

The function definition for PutFile is:

PutFile(Source, Destination, OverWrite := true, ParentRev := "", Locale := "en")

The parameters are all explained in the source code, but for now we are only concerned with the Source and Destination parameters.

Source  - The path and file name to upload. This is relative to A_WorkingDir
              unless a full path is specified. This should NOT point to a folder.
                      
Destination - The path to the file you want to write to. This is relative to the app 
                   folder or the Dropbox root depending on the AccessLevel. This parameter 
                   should NOT point to a folder.

FileInfo := MyDB.PutFile("working-draft.txt", "/magnum-opus.txt")

If all goes well, working-draft.txt will now be in the root of your app folder (or Dropbox folder, depending on your app's access type) and it will be called magnum-opus.txt. The variable FileInfo will be an object containing the metadata of the newly uploaded file. It will look something like this:

{
    'bytes': 77,
    'icon': 'page_white_text',
    'is_dir': False,
    'mime_type': 'text/plain',
    'modified': 'Wed, 20 Jul 2011 22:04:50 +0000',
    'path': '/magnum-opus.txt',
    'rev': '362e2029684fe',
    'revision': 221922,
    'root': 'dropbox',
    'size': '77 bytes',
    'thumb_exists': False
}

Listing folders

If you peruse the various entries in the metadata above, you'll get a good sense for all info we can gather from the file. You can get this info for an entire folder by using the GetMetadata() method.

FolderInfo := GetMetadata("/Sample Folder")

The returned object will contain information about the files and folders in the path given. It looks something like this:

{'bytes': 0,
 'contents': [{'bytes': 0,
               'icon': 'folder',
               'is_dir': True,
               'modified': 'Thu, 25 Aug 2011 00:03:15 +0000',
               'path': '/Sample Folder',
               'rev': '803beb471',
               'revision': 8,
               'root': 'dropbox',
               'size': '0 bytes',
               'thumb_exists': False},
              {'bytes': 77,
               'icon': 'page_white_text',
               'is_dir': False,
               'mime_type': 'text/plain',
               'modified': 'Wed, 20 Jul 2011 22:04:50 +0000',
               'path': '/magnum-opus.txt',
               'rev': '362e2029684fe',
               'revision': 221922,
               'root': 'dropbox',
               'size': '77 bytes',
               'thumb_exists': False}],
 'hash': 'efdac89c4da886a9cece1927e6c22977',
 'icon': 'folder',
 'is_dir': True,
 'path': '/',
 'root': 'app_folder',
 'size': '0 bytes',
 'thumb_exists': False}

In the example above, the app folder root contains a directory named Sample Folder and the file we just uploaded named magnum-opus.txt. You'll also see other various but vital bits of information such as the exact location of the file (path), file sizes (bytes), last modified date (modified), and more. If you want to tell if something has changed in the directory, you'll want to store and compare the hash parameter. Similarly, a file's rev parameter tells you if the file has changed. It's useful to keep track of the status of your files, as we'll see in the following example.

Downloading files

Some time has passed and you're ready to start editing that magnum opus of yours again. We'll need the GetFile() method to download the file.

FileInfo := MyDB.GetFile("magnum-opus.txt", "working-draft.txt")

In addition to the file, the method also returns the file's metadata at its current revision. Every time a change is made to the file, the
rev
field of the file's metadata changes as well. By saving the revision when you download the file, you'll be able to tell if that file has been updated by another computer or device and choose to download the newer revision of that file.

The complete code

For those keeping score at home, here's the full source to this guide. Make sure to create a magnum-opus.txt file to get it to work fully. Also remember to insert your app key, app secret, and access type.

; AutoExecute
    #NoEnv
    #SingleInstance force 
    
    #Include Class DBox.ahk
    
    MyDB := new DBox("APP_KEY", "APP_SECRET", "ACCESS_TYPE")
    SplashTextOn , , , Getting Request Tokens
    MyDB.GetAuthorizationTokens()
    SplashTextOn , , , Getting User Authorization
    MyDB.GetUserAuthorization("[email protected]")  ; Your email address goes here
    SplashTextOn , , , Getting Access Tokens
    MyDB.GetAccessTokens()
    SplashTextOff

    FileInfo := MyDB.PutFile("working-draft.txt", "/magnum-opus.txt")
    Display(FileInfo)

    FolderInfo := GetMetadata("/Sample Folder")
    Display(FolderInfo)

    FileInfo := MyDB.GetFile("magnum-opus.txt", "working-draft.txt")
    Display(FileInfo)
return

; Everything below here is just used to display the returned object
; This wouldn't typically be necessary.

;Convert the returned object to a string for display
ObjToStr(Obj, Indent="`t", Rows="`n", Equal=" = ", Depth=7, CurIndent="") {	; converts object to 

string
    For k,v in Obj
        ToReturn .= CurIndent . k . (IsObject(v) && depth>1 ? Rows . ObjToStr(v, Indent, Rows, Equal, 

Depth-1, CurIndent . Indent) : Equal . v) . Rows
    return RTrim(ToReturn, Rows)
}	; http://www.autohotkey.com/forum/post-426623.html#426623

Display(Obj)
{
    global MyDB
    
    Result := MyDB.LastResponse "`n" . ObjToStr(Obj, "      ")
    MsgBox % Result
}

SDK Documentation

I encourage you to browse the SDK source code. I've tried to document all of the methods and parameters fully. Also be sure to take a look at the official reference for the Core API.

Next steps

And with that you should be equipped with most everything you need to get started with the Core API. If you're still not sure about something, post your question here. Good luck!

Sign In