Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 90 lines (54 sloc) 3.907 kb
9fd1be1 Evan Meagher Started README content.
authored
1 # dropbox-node
2
e9bf3ab Evan Meagher Update README to reflect changes to API semantics.
authored
3 An OAuth-enabled Node.js client for working with the Dropbox API.
aaae1c7 Evan Meagher Added incomplete disclaimer to README.
authored
4
6232247 Evan Meagher Added installation and todo blurbs.
authored
5 ## Installation
6
e9bf3ab Evan Meagher Update README to reflect changes to API semantics.
authored
7 dropbox-node depends on [node-oauth](http://github.com/ciaranj/node-oauth).
6232247 Evan Meagher Added installation and todo blurbs.
authored
8
993b35f Evan Meagher Added instructions for installation via npm.
authored
9 To install via npm
10
11 npm install dropbox
12
13 To install by hand, download the module and create a symlink in `~/.node_libraries`
6232247 Evan Meagher Added installation and todo blurbs.
authored
14
15 $ ln -s /path/to/dropbox-node/ ~/.node_libraries/dropbox-node
16
ae5b4af Evan Meagher Wrote usage and testing sections.
authored
17 ## Usage
18
e9bf3ab Evan Meagher Update README to reflect changes to API semantics.
authored
19 To start, grab a consumer key and secret from [dropbox.com/developers](https://dropbox.com/developers).
ae5b4af Evan Meagher Wrote usage and testing sections.
authored
20
e9bf3ab Evan Meagher Update README to reflect changes to API semantics.
authored
21 ### Object construction and access key pair retrieval
22 First construct a DropboxClient object, passing in the consumer key and secret.
ae5b4af Evan Meagher Wrote usage and testing sections.
authored
23
e9bf3ab Evan Meagher Update README to reflect changes to API semantics.
authored
24 var dropbox = new DropboxClient(consumer_key, consumer_secret)
ae5b4af Evan Meagher Wrote usage and testing sections.
authored
25
e9bf3ab Evan Meagher Update README to reflect changes to API semantics.
authored
26 Before calling any Dropbox API methods, `getAccessToken` must be called in order to initialize the OAuth credentials.
ae5b4af Evan Meagher Wrote usage and testing sections.
authored
27
e9bf3ab Evan Meagher Update README to reflect changes to API semantics.
authored
28 dropbox.getAccessToken(dropbox_email, dropbox_password, callback)
ae5b4af Evan Meagher Wrote usage and testing sections.
authored
29
e9bf3ab Evan Meagher Update README to reflect changes to API semantics.
authored
30 The callback given to `getAccessToken` takes an error object, an access token, and an access token secret (see example below).
ae5b4af Evan Meagher Wrote usage and testing sections.
authored
31
32 ### Calling API methods
33
e9bf3ab Evan Meagher Update README to reflect changes to API semantics.
authored
34 dropbox-node provides methods covering [each of the Dropbox API methods](https://www.dropbox.com/developers/docs), excluding account creation.
ae5b4af Evan Meagher Wrote usage and testing sections.
authored
35
36 For example, to fetch and print the display name and email address associated with your account:
37
e9bf3ab Evan Meagher Update README to reflect changes to API semantics.
authored
38 dropbox.getAccountInfo(function (err, data) {
39 if (err) console.log('Error: ' + err)
40 else console.log(data.display_name + ', ' + data.email)
41 })
42
43 Note that (in most cases) `getAccessToken` must be called prior to interacting with the rest of the Dropbox API. This means that the API methods must be invoked within the callback passed to `getAccessToken` unless it is guaranteed that `getAccessToken` was called previously. As an example of this latter case, if building a web app, one could call API methods directly in a route that can only be accessed after going through a sign-in phase in which a call to `getAccessToken` is made.
ae5b4af Evan Meagher Wrote usage and testing sections.
authored
44
81ba78e Evan Meagher Add link in README to file browser walkthrough.
authored
45 Here we upload a file and remotely move it around before deleting it.
ae5b4af Evan Meagher Wrote usage and testing sections.
authored
46
e9bf3ab Evan Meagher Update README to reflect changes to API semantics.
authored
47 dropbox.getAccessToken(email, pwd, function (err, token, secret) {
48 // Upload foo.txt to the Dropbox root directory.
49 dropbox.putFile('foo.txt', '', function (err, data) {
50 if (err) return console.error(err)
51
5e24ff7 Evan Meagher Fix broken control flow of example in README.
authored
52 // Move it into the Public directory.
e9bf3ab Evan Meagher Update README to reflect changes to API semantics.
authored
53 dropbox.move('foo.txt', 'Public/foo.txt', function (err, data) {
54 if (err) return console.error(err)
55
56 // Delete the file.
e0570bf Evan Meagher s/function(/function (/
authored
57 dropbox.deleteItem('Public/foo.txt', function (err, data) {
355a639 Evan Meagher Remove semicolon in README.
authored
58 if (err) console.error(err.stack)
e9bf3ab Evan Meagher Update README to reflect changes to API semantics.
authored
59 })
60 })
61 })
62 })
ae5b4af Evan Meagher Wrote usage and testing sections.
authored
63
81ba78e Evan Meagher Add link in README to file browser walkthrough.
authored
64 For a more practical example, check out this [walkthrough of building a simple Dropbox file browser](http://evanmeagher.net/2010/10/dropbox-file-browser).
65
e9bf3ab Evan Meagher Update README to reflect changes to API semantics.
authored
66 ### API method optional argument
67
68 Optional arguments (as specified in the [Dropbox API documentation](https://www.dropbox.com/developers/docs)) can be given to API methods via an argument object.
69
70 For example, here we call `getAccountInfo` and direct the API to include the HTTP status code in the response.
71
72 dropbox.getAccountInfo({ status_in_response: true }, callback)
73
74 Each API method (except `getAccessToken`) can take as optional arguments an access token and an access token secret as strings. This is the one way to get around having to call `getAccessToken` in cases where a valid key pair is known.
75
76 For example, here we fetch the metadata about the Dropbox root directory, passing in an explicit key pair stored in variables.
77
78 dropbox.getMetadata('', { token: token, secret: secret }, callback)
79
ae5b4af Evan Meagher Wrote usage and testing sections.
authored
80 ## Testing
81
e9bf3ab Evan Meagher Update README to reflect changes to API semantics.
authored
82 dropbox-node depends on [jasmine-node](http://github.com/mhevery/jasmine-node) for testing. Note that the currently-implemented tests are trivial at best.
ae5b4af Evan Meagher Wrote usage and testing sections.
authored
83
84 Run specs with `node specs.js` from the root `dropbox-node` directory.
85
6232247 Evan Meagher Added installation and todo blurbs.
authored
86 ## TODO
87 * Improve test coverage.
a8ad6eb Evan Meagher Add documentation todo item.
authored
88 * Improve documentation.
ae5b4af Evan Meagher Wrote usage and testing sections.
authored
89 * Add ability to interact with application sandboxes.
Something went wrong with that request. Please try again.