Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 113 lines (69 sloc) 5.581 kb
9fd1be1d »
2010-10-16 Started README content.
1 # dropbox-node
2
e9bf3abc »
2011-01-08 Update README to reflect changes to API semantics.
3 An OAuth-enabled Node.js client for working with the Dropbox API.
aaae1c79 »
2010-10-16 Added incomplete disclaimer to README.
4
1ce6cb9c »
2011-02-25 Add disclaimer about lack of official Dropbox support for web apps.
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
62322473 »
2010-10-17 Added installation and todo blurbs.
9 ## Installation
10
e9bf3abc »
2011-01-08 Update README to reflect changes to API semantics.
11 dropbox-node depends on [node-oauth](http://github.com/ciaranj/node-oauth).
62322473 »
2010-10-17 Added installation and todo blurbs.
12
993b35fc »
2010-10-18 Added instructions for installation via npm.
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`
62322473 »
2010-10-17 Added installation and todo blurbs.
18
19 $ ln -s /path/to/dropbox-node/ ~/.node_libraries/dropbox-node
20
ae5b4afb »
2010-10-17 Wrote usage and testing sections.
21 ## Usage
22
e9bf3abc »
2011-01-08 Update README to reflect changes to API semantics.
23 To start, grab a consumer key and secret from [dropbox.com/developers](https://dropbox.com/developers).
ae5b4afb »
2010-10-17 Wrote usage and testing sections.
24
e9bf3abc »
2011-01-08 Update README to reflect changes to API semantics.
25 ### Object construction and access key pair retrieval
26 First construct a DropboxClient object, passing in the consumer key and secret.
ae5b4afb »
2010-10-17 Wrote usage and testing sections.
27
e9bf3abc »
2011-01-08 Update README to reflect changes to API semantics.
28 var dropbox = new DropboxClient(consumer_key, consumer_secret)
ae5b4afb »
2010-10-17 Wrote usage and testing sections.
29
5444ec6f »
2011-02-25 Update README to reflect changes to ctor and addition of `createAccou…
30 Before calling any Dropbox API methods, an access token pair must be obtained. This can be done one of two ways:
ae5b4afb »
2010-10-17 Wrote usage and testing sections.
31
5444ec6f »
2011-02-25 Update README to reflect changes to ctor and addition of `createAccou…
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)
ae5b4afb »
2010-10-17 Wrote usage and testing sections.
40
51d326e5 »
2011-05-14 Add password-storage warning to README.
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.
ae5b4afb »
2010-10-17 Wrote usage and testing sections.
42
43 ### Calling API methods
44
5444ec6f »
2011-02-25 Update README to reflect changes to ctor and addition of `createAccou…
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:
ae5b4afb »
2010-10-17 Wrote usage and testing sections.
46
e9bf3abc »
2011-01-08 Update README to reflect changes to API semantics.
47 dropbox.getAccountInfo(function (err, data) {
48 if (err) console.log('Error: ' + err)
49 else console.log(data.display_name + ', ' + data.email)
50 })
51
938a22ae »
2011-05-14 Update README.
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.
ae5b4afb »
2010-10-17 Wrote usage and testing sections.
53
81ba78ea »
2010-11-18 Add link in README to file browser walkthrough.
54 Here we upload a file and remotely move it around before deleting it.
ae5b4afb »
2010-10-17 Wrote usage and testing sections.
55
e9bf3abc »
2011-01-08 Update README to reflect changes to API semantics.
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
5e24ff71 »
2010-11-18 Fix broken control flow of example in README.
61 // Move it into the Public directory.
e9bf3abc »
2011-01-08 Update README to reflect changes to API semantics.
62 dropbox.move('foo.txt', 'Public/foo.txt', function (err, data) {
63 if (err) return console.error(err)
64
65 // Delete the file.
e0570bfc »
2011-01-08 s/function(/function (/
66 dropbox.deleteItem('Public/foo.txt', function (err, data) {
355a6396 »
2011-01-19 Remove semicolon in README.
67 if (err) console.error(err.stack)
e9bf3abc »
2011-01-08 Update README to reflect changes to API semantics.
68 })
69 })
70 })
71 })
ae5b4afb »
2010-10-17 Wrote usage and testing sections.
72
81ba78ea »
2010-11-18 Add link in README to file browser walkthrough.
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
938a22ae »
2011-05-14 Update README.
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
e9bf3abc »
2011-01-08 Update README to reflect changes to API semantics.
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
938a22ae »
2011-05-14 Update README.
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.
e9bf3abc »
2011-01-08 Update README to reflect changes to API semantics.
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
ae5b4afb »
2010-10-17 Wrote usage and testing sections.
104 ## Testing
105
938a22ae »
2011-05-14 Update README.
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.
ae5b4afb »
2010-10-17 Wrote usage and testing sections.
107
108 Run specs with `node specs.js` from the root `dropbox-node` directory.
109
62322473 »
2010-10-17 Added installation and todo blurbs.
110 ## TODO
111 * Improve test coverage.
a8ad6ebd »
2010-11-08 Add documentation todo item.
112 * Improve documentation.
ae5b4afb »
2010-10-17 Wrote usage and testing sections.
113 * Add ability to interact with application sandboxes.
Something went wrong with that request. Please try again.