Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 114 lines (69 sloc) 5.581 kb
9fd1be1 @evnm Started README content.
authored
1 # dropbox-node
2
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
3 An OAuth-enabled Node.js client for working with the Dropbox API.
aaae1c7 @evnm Added incomplete disclaimer to README.
authored
4
1ce6cb9 @evnm Add disclaimer about lack of official Dropbox support for web apps.
authored
5 ### DISCLAIMER
6
7 The current Dropbox API is targeted for mobile applications, and thus web apps using it aren't "officially supported." Note that the way dropbox-node currently handles the OAuth dance will likely change when the Dropbox web app API becomes available. More info [here](https://www.dropbox.com/developers/web_docs).
8
6232247 @evnm Added installation and todo blurbs.
authored
9 ## Installation
10
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
11 dropbox-node depends on [node-oauth](http://github.com/ciaranj/node-oauth).
6232247 @evnm Added installation and todo blurbs.
authored
12
993b35f @evnm Added instructions for installation via npm.
authored
13 To install via npm
14
15 npm install dropbox
16
17 To install by hand, download the module and create a symlink in `~/.node_libraries`
6232247 @evnm Added installation and todo blurbs.
authored
18
19 $ ln -s /path/to/dropbox-node/ ~/.node_libraries/dropbox-node
20
ae5b4af @evnm Wrote usage and testing sections.
authored
21 ## Usage
22
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
23 To start, grab a consumer key and secret from [dropbox.com/developers](https://dropbox.com/developers).
ae5b4af @evnm Wrote usage and testing sections.
authored
24
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
25 ### Object construction and access key pair retrieval
26 First construct a DropboxClient object, passing in the consumer key and secret.
ae5b4af @evnm Wrote usage and testing sections.
authored
27
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
28 var dropbox = new DropboxClient(consumer_key, consumer_secret)
ae5b4af @evnm Wrote usage and testing sections.
authored
29
5444ec6 @evnm Update README to reflect changes to ctor and addition of `createAccount`...
authored
30 Before calling any Dropbox API methods, an access token pair must be obtained. This can be done one of two ways:
ae5b4af @evnm Wrote usage and testing sections.
authored
31
5444ec6 @evnm Update README to reflect changes to ctor and addition of `createAccount`...
authored
32 1. If the access token and secret are known a priori, they can be passed directly into the DropboxClient constructor.
33
34 var dropbox = new DropboxClient(consumer_key, consumer_secret,
35 access_token, access_token_secret)
36
37 2. Otherwise, `getAccessToken` must be called in order to initialize the OAuth credentials.
38
39 dropbox.getAccessToken(dropbox_email, dropbox_password, callback)
ae5b4af @evnm Wrote usage and testing sections.
authored
40
51d326e @evnm Add password-storage warning to README.
authored
41 The callback given to `getAccessToken` takes an error object, an access token, and an access token secret (see example below). **Please note that users' passwords should never be stored.** It is best to acquire a token once and then use it for all subsequent requests.
ae5b4af @evnm Wrote usage and testing sections.
authored
42
43 ### Calling API methods
44
5444ec6 @evnm Update README to reflect changes to ctor and addition of `createAccount`...
authored
45 dropbox-node provides methods covering [each of the Dropbox API methods](https://www.dropbox.com/developers/docs). For example, to fetch and print the display name and email address associated with your account:
ae5b4af @evnm Wrote usage and testing sections.
authored
46
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
47 dropbox.getAccountInfo(function (err, data) {
48 if (err) console.log('Error: ' + err)
49 else console.log(data.display_name + ', ' + data.email)
50 })
51
938a22a @evnm Update README.
authored
52 Note that (at least at the start of a user's session) a valid access token pair must be obtained 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 @evnm Wrote usage and testing sections.
authored
53
81ba78e @evnm Add link in README to file browser walkthrough.
authored
54 Here we upload a file and remotely move it around before deleting it.
ae5b4af @evnm Wrote usage and testing sections.
authored
55
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
56 dropbox.getAccessToken(email, pwd, function (err, token, secret) {
57 // Upload foo.txt to the Dropbox root directory.
58 dropbox.putFile('foo.txt', '', function (err, data) {
59 if (err) return console.error(err)
60
5e24ff7 @evnm Fix broken control flow of example in README.
authored
61 // Move it into the Public directory.
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
62 dropbox.move('foo.txt', 'Public/foo.txt', function (err, data) {
63 if (err) return console.error(err)
64
65 // Delete the file.
e0570bf @evnm s/function(/function (/
authored
66 dropbox.deleteItem('Public/foo.txt', function (err, data) {
355a639 @evnm Remove semicolon in README.
authored
67 if (err) console.error(err.stack)
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
68 })
69 })
70 })
71 })
ae5b4af @evnm Wrote usage and testing sections.
authored
72
81ba78e @evnm Add link in README to file browser walkthrough.
authored
73 For a more practical example, check out this [walkthrough of building a simple Dropbox file browser](http://evanmeagher.net/2010/10/dropbox-file-browser).
74
938a22a @evnm Update README.
authored
75 ### Stream-based file-downloading
76
77 As of v0.3.1, dropbox-node exposes a method `getFileStream` that allows stream-based file-downloading. This is useful when downloading large files that wouldn't easily fit in memory and thus don't play nicely with `getFile`.
78
79 `getFileStream` returns an EventEmitter representing the request. The target file will be downloaded in chunks and dealt with according to the callbacks you register. Here we fetch a large file and write it to disk:
80
81 var request = dropbox.getFileStream("path/to/huge/file")
82 , write_stream = require('fs').createWriteStream("out")
83
84 request.on('response', function (response) {
85 res.on('data', function (chunk) { write_stream.write(chunk) })
86 res.on('end', function () { write_stream.end() })
87 })
88 request.end()
89
90 ### Optional arguments
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
91
92 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.
93
94 For example, here we call `getAccountInfo` and direct the API to include the HTTP status code in the response.
95
96 dropbox.getAccountInfo({ status_in_response: true }, callback)
97
938a22a @evnm Update README.
authored
98 Each method (except `getAccessToken`) can optionally take 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.
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
99
100 For example, here we fetch the metadata about the Dropbox root directory, passing in an explicit key pair stored in variables.
101
102 dropbox.getMetadata('', { token: token, secret: secret }, callback)
103
ae5b4af @evnm Wrote usage and testing sections.
authored
104 ## Testing
105
938a22a @evnm Update README.
authored
106 dropbox-node depends on [jasmine-node](http://github.com/mhevery/jasmine-node) for testing. Note that the currently-implemented tests are trivial, due to a lack of a way to effectively mock the Dropbox API.
ae5b4af @evnm Wrote usage and testing sections.
authored
107
108 Run specs with `node specs.js` from the root `dropbox-node` directory.
109
6232247 @evnm Added installation and todo blurbs.
authored
110 ## TODO
111 * Improve test coverage.
a8ad6eb @evnm Add documentation todo item.
authored
112 * Improve documentation.
ae5b4af @evnm Wrote usage and testing sections.
authored
113 * Add ability to interact with application sandboxes.
Something went wrong with that request. Please try again.