Datastores

Files

Datastore API for JavaScript documentation

Datastores are an easy way to keep an app's per-user data — like settings, bookmarks, or game state — in sync across multiple devices and operating systems. Datastores are simple embedded databases, which are synced to Dropbox.

This reference details the full set of classes needed when working with datastores. You can also read the Datastore API tutorial for a detailed example of how to use them.

General information

The JavaScript Datastore API supports Internet Explorer 10, Safari 6 on Mac OS, and recent versions of Firefox and Chrome. Support for other environments may be added in the future.

Shared datastores

Apps may want to share data between users. With the Datastore API, apps can share a datastore across multiple Dropbox accounts. The unit of sharing is a single datastore, and one or more datastores may be shared between accounts. Any datastore with a shareable ID (see "Private or shareable datastores" below) can be shared by assigning roles to principals, creating an access control list. Any Dropbox account with the correct permissions will then be able to open the shared datastore by ID.

There are two available principals to whom you may apply a role:

Dropbox.Datastore.PUBLIC – The role will apply to all Dropbox users.

Dropbox.Datastore.TEAM – The role will apply to everyone on the user's team (only applicable for Dropbox for Business accounts).

There are four available roles:

Dropbox.Datastore.NONE – The principal has no access to this datastore.

Dropbox.Datastore.VIEWER – The principal is able to view this datastore.

Dropbox.Datastore.EDITOR – The principal is able to edit this datastore.

Dropbox.Datastore.OWNER – The principal is the owner of this datastore. This role cannot be assigned directly. The user who created a datastore is always that datastore's owner.

Private or shareable datastores

Datastores can be created in 2 different ways, and the choice affects how they can be used. Each type of datastore can be identified by its ID.

Datastores with private IDs are created using DatastoreManager openOrCreateDatastore(datastoreId, callback). Private IDs are meaningful to the developer of the app, such as "default" (for the default datastore) or "settings". The scope of private IDs is the current user-app pair. Two different devices can create datastores with the same private ID while offline, and their data will be merged when they come online.

Private datastore IDs can be 1-64 characters containing only lowercase letters, digits, dot, hyphen or underscore, and they must not begin or end with dot.

Datastores with shareable IDs are created using DatastoreManager createDatastore(callback) which allows them to be shared between users. Their IDs are auto-generated and are not only unique for the user-app pair, they're also unique across Dropbox. Shareable IDs are more appropriate when treating each datastore as an individual document where users may create an unknown number of them.

Shareable datastore IDs (generated by the SDK) are a dot followed by 1-63 characters containing uppercase letters, lowercase letters, hyphen or underscore.

Storage size limits

Datastores have limits on their maximum size to ensure good performance across platforms. You should keep these in mind as guidelines when modeling your datastores.

Your app can store up to 5MB of data across all its datastores without counting against the user's storage quota. Any data beyond the first 5MB is factored into the user's Dropbox storage quota, and writing can be limited in these cases when a user is over quota. Sizes are calculated as:

The size of a datastore is calculated by summing the size of all records, plus 1000 bytes for the datastore itself.

The size of a record is calculated by summing the size of all values in all fields, plus 100 bytes for the record itself.

The size of a field is a fixed 100 bytes for the field itself plus:

for string or bytes values, the length in bytes of the value.

for List values, 20 bytes for each list element plus the size of each element.

for all other types, no additional contribution.

The size of changes made in a transaction is calculated by summing the size of each change, plus 100 bytes for the delta itself. The size of each change is calculated by summing the size of the values contained in the change (for field updates and list put and insert operations) plus 100 bytes for the change itself.

Maximum record size

100 KiB

Maximum number of records per datastore

100,000

Maximum datastore size

10 MiB

Maximum size of a single transaction

2 MiB

Dropbox.Client

Represents a user accessing the application.

Instance Methods

constructor(options)

Dropbox API client representing an user or an application.

For an optimal user experience, applications should use a single client for
all Dropbox interactions.

In most cases, the process will involve sending the user to an
authorization server on the Dropbox servers. If the user clicks "Allow",
the application will be authorized. If the user clicks "Deny", the method
will pass a Dropbox.AuthError to its callback, and the error's code will
be Dropbox.AuthError.ACCESS_DENIED.

Parameters

(optional) called when the authentication completes; if successful, the second parameter is this client and the first parameter is null

Options parameter

interactive (Boolean)

if false, the authentication process will stop and call the callback whenever it would have to wait for an authorization; true by default; this is useful for determining if the authDriver has cached credentials available

Returns

this, for easy call chaining

Boolean isAuthenticated()

Checks if this client can perform API calls on behalf of a user.

Returns

true if this client has a user's OAuth 2 access token and can be used to make API calls; false otherwise

XMLHttpRequest signOut(options, callback)

Invalidates and forgets the user's Dropbox OAuth 2 access token.

This should be called when the user explicitly signs off from your
application, to meet the users' expectation that after they sign out, their
access tokens will not be persisted on the machine.

Parameters

called with the result of the /account/info HTTP request; if the call succeeds, the second parameter is a Dropbox.AccountInfo instance, the third parameter is the parsed JSON data behind the Dropbox.AccountInfo instance, and the first parameter is null

Options parameter

httpCache (Boolean)

if true, the API request will be set to allow HTTP caching to work; by default, requests are set up to avoid CORS preflights; setting this option can make sense when making the same request repeatedly

Returns

the XHR object used for this API call

void getUserInfo()

Backwards-compatible name of getAccountInfo.

@deprecated

See Also

Some options are silently ignored in Internet Explorer 9 and below, due to
insufficient support in its proprietary XDomainRequest replacement for XHR.
Currently, the options are: arrayBuffer, blob, length, start.

Parameters

path
(String)

the path of the file to be read, relative to the user's Dropbox or to the application's folder

called with the result of the /files (GET) HTTP request; the second parameter is the contents of the file, the third parameter is a Dropbox.File.Stat instance describing the file, and the first parameter is null; if the start and/or length options are specified, the fourth parameter describes the subset of bytes read from the file

Options parameter

versionTag (String)

the tag string for the desired version of the file contents; the most recent version is retrieved by default

rev (String)

alias for "versionTag" that matches the HTTP API

arrayBuffer (Boolean)

if true, the file's contents will be passed to the callback in an ArrayBuffer; this is the recommended method of reading non-UTF8 data such as images, as it is well supported across modern browsers; requires XHR Level 2 support, which is not available in IE <= 9

blob (Boolean)

if true, the file's contents will be passed to the callback in a Blob; this is a good method of reading non-UTF8 data, such as images; requires XHR Level 2 support, which is not available in IE <= 9

buffer (Boolean)

if true, the file's contents will be passed to the callback in a node.js Buffer; this only works on node.js

binary (Boolean)

if true, the file will be retrieved as a binary string; the default is an UTF-8 encoded string; this relies on hacks and should not be used if the environment supports XHR Level 2 API

length (Number)

the number of bytes to be retrieved from the file; if the start option is not present, the last "length" bytes will be read; by default, the entire file is read

start (Number)

the 0-based offset of the first byte to be retrieved; if the length option is not present, the bytes between "start" and the file's end will be read; by default, the entire file is read

httpCache (Boolean)

if true, the API request will be set to allow HTTP caching to work; by default, requests are set up to avoid CORS preflights; setting this option can make sense when making the same request repeatedly

Returns

the XHR object used for this API call

XMLHttpRequest writeFile(path, data, options, callback)

Store a file into a user's Dropbox.

Parameters

path
(String)

the path of the file to be created, relative to the user's Dropbox or to the application's folder

data
(String, ArrayBuffer, ArrayBufferView, Blob, File, Buffer)

the contents written to the file; if a File is passed, its name is ignored

called with the result of the /files (POST) HTTP request; the second parameter is a Dropbox.File.Stat instance describing the newly created file, and the first parameter is null

Options parameter

lastVersionTag (String)

the identifier string for the version of the file's contents that was last read by this program, used for conflict resolution; for best results, use the versionTag attribute value from the Dropbox.File.Stat instance provided by readFile

parentRev (String)

alias for "lastVersionTag" that matches the HTTP API

noOverwrite (Boolean)

if set, the write will not overwrite a file with the same name that already exists; instead the contents will be written to a similarly named file (e.g. "notes (1).txt" instead of "notes.txt")

Returns

the XHR object used for this API call

XMLHttpRequest resumableUploadStep(data, cursor, callback)

Atomic step in a resumable file upload.

Parameters

data
(String, ArrayBuffer, ArrayBufferView, Blob, File, Buffer)

the file contents fragment to be uploaded; if a File is passed, its name is ignored

called with the result of the /chunked_upload HTTP request; the second parameter is a Dropbox.Http.UploadCursor instance describing the progress of the upload operation, and the first parameter is null if no error occurs

Returns

the XHR object used for this API call

XMLHttpRequest resumableUploadFinish(path, options, callback)

Finishes a resumable file upload.

Parameters

path
(String)

the path of the file to be created, relative to the user's Dropbox or to the application's folder

called with the result of the /files (POST) HTTP request; the second parameter is a Dropbox.File.Stat instance describing the newly created file, and the first parameter is null

Options parameter

lastVersionTag (String)

the identifier string for the version of the file's contents that was last read by this program, used for conflict resolution; for best results, use the versionTag attribute value from the Dropbox.File.Stat instance provided by readFile

parentRev (String)

alias for "lastVersionTag" that matches the HTTP API

noOverwrite (Boolean)

if set, the write will not overwrite a file with the same name that already exists; instead the contents will be written to a similarly named file (e.g. "notes (1).txt" instead of "notes.txt")

Returns

the XHR object used for this API call

XMLHttpRequest stat(path, options, callback)

Reads the metadata of a file or folder in a user's Dropbox.

Parameters

path
(String)

the path to the file or folder whose metadata will be read, relative to the user's Dropbox or to the application's folder

called with the result of the /metadata HTTP request; if the call succeeds, the second parameter is a Dropbox.File.Stat instance describing the file / folder, and the first parameter is null; if the readDir option is true and the call succeeds, the third parameter is an array of Dropbox.File.Stat instances describing the folder's entries

Options parameter

version (Number)

if set, the call will return the metadata for the given revision of the file / folder; the latest version is used by default

removed (Boolean)

if set to true, the results will include files and folders that were deleted from the user's Dropbox

deleted (Boolean)

alias for "removed" that matches the HTTP API; using this alias is not recommended, because it may cause confusion with JavaScript's delete operation

readDir (Boolean, Number)

only meaningful when stat-ing folders; if this is set, the API call will also retrieve the folder's contents, which is passed into the callback's third parameter; if this is a number, it specifies the maximum number of files and folders that should be returned; the default limit is 10,000 items; if the limit is exceeded, the call will fail with an error

versionTag (String)

the tag string for the desired version of the file or folder metadata; the most recent version is retrieved by default

rev (String)

alias for "versionTag" that matches the HTTP API

contentHash (String)

used for saving bandwidth when getting a folder's contents; if this value is specified and it matches the folder's contents, the call will fail with a Dropbox.ApiError.NO_CONTENT error status; a folder's version identifier can be obtained from the contentHash property of the Stat instance describing the folder

hash (String)

alias for "contentHash" that matches the HTTP API

httpCache (Boolean)

if true, the API request will be set to allow HTTP caching to work; by default, requests are set up to avoid CORS preflights; setting this option can make sense when making the same request repeatedly

Returns

the XHR object used for this API call

XMLHttpRequest readdir(path, options, callback)

Lists the files and folders inside a folder in a user's Dropbox.

Parameters

path
(String)

the path to the folder whose contents will be retrieved, relative to the user's Dropbox or to the application's folder

called with the result of the /metadata HTTP request; if the call succeeds, the second parameter is an array containing the names of the files and folders in the given folder, the third parameter is a Dropbox.File.Stat instance describing the folder, the fourth parameter is an array of Dropbox.File.Stat instances describing the folder's entries, and the first parameter is null

Options parameter

removed (Boolean)

if set to true, the results will include files and folders that were deleted from the user's Dropbox

deleted (Boolean)

alias for "removed" that matches the HTTP API; using this alias is not recommended, because it may cause confusion with JavaScript's delete operation

limit (Boolean, Number)

the maximum number of files and folders that should be returned; the default limit is 10,000 items; if the limit is exceeded, the call will fail with an error

versionTag (String)

the tag string for the desired version of the file or folder metadata; the most recent version is retrieved by default

contentHash (String)

used for saving bandwidth when getting a folder's contents; if this value is specified and it matches the folder's contents, the call will fail with a Dropbox.ApiError.NO_CONTENT error status; a folder's version identifier can be obtained from the contentHash property of the Stat instance describing the folder

httpCache (Boolean)

if true, the API request will be set to allow HTTP caching to work; by default, requests are set up to avoid CORS preflights; setting this option can make sense when making the same request repeatedly

called with the result of the /shares or /media HTTP request; if the call succeeds, the second parameter is a Dropbox.File.ShareUrl instance, and the first parameter is null

Options parameter

download (Boolean)

if set, the URL will be a direct download URL, instead of the usual Dropbox preview URLs; direct download URLs are short-lived (currently 4 hours), whereas regular URLs virtually have no expiration date (currently set to 2030); no direct download URLs can be generated for directories

downloadHack (Boolean)

if set, a long-living download URL will be generated by asking for a preview URL and using the officially documented hack at https://www.dropbox.com/help/201 to turn the preview URL into a download URL

long (Boolean)

if set, the URL will not be shortened using Dropbox's shortner; the download and downloadHack options imply long

longUrl (Boolean)

synonym for long; makes life easy for RhinoJS users

Returns

the XHR object used for this API call

XMLHttpRequest history(path, options, callback)

Retrieves the revision history of a file in a user's Dropbox.

Parameters

path
(String)

the path to the file whose revision history will be retrieved, relative to the user's Dropbox or to the application's folder

called with the result of the /thumbnails HTTP request; if the call succeeds, the second parameter is the image data as a String or Blob, the third parameter is a Dropbox.File.Stat instance describing the thumbnailed file, and the first argument is null

Options parameter

png (Boolean)

if true, the thumbnail's image will be a PNG file; the default thumbnail format is JPEG

format (String)

value that gets passed directly to the API; this is intended for newly added formats that the API may not support; use options such as "png" when applicable

if true, the file's contents will be passed to the callback in an ArrayBuffer; this is the recommended method of reading thumbnails, as it is well supported across modern browsers; requires XHR Level 2 support, which is not available in IE <= 9

blob (Boolean)

if true, the file's contents will be passed to the callback in a Blob; requires XHR Level 2 support, which is not available in IE <= 9

buffer (Boolean)

if true, the file's contents will be passed to the callback in a node.js Buffer; this only works on node.js

called with the result of the /restore HTTP request; if the call succeeds, the second parameter is a Dropbox.File.Stat instance describing the file after the revert operation, and the first parameter is null

See Also

This method is intended to make full sync implementations easier and more
performant. Each call returns a cursor that can be used in a future call
to obtain all the changes that happened in the user's Dropbox (or
application directory) between the two calls.

called with the result of the /delta HTTP request; if the call succeeds, the second parameter is a Dropbox.Http.PulledChanges describing the changes to the user's Dropbox since the pullChanges call that produced the given cursor, and the first parameter is null

Parameters

called with the result of the /fileops/create_folder HTTP request; if the call succeeds, the second parameter is a Dropbox.File.Stat instance describing the newly created folder, and the first parameter is null

Returns

the XHR object used for this API call

XMLHttpRequest remove(path, callback)

Removes a file or directory from a user's Dropbox.

Parameters

path
(String)

the path of the file to be read, relative to the user's Dropbox or to the application's folder

called with the result of the /fileops/delete HTTP request; if the call succeeds, the second parameter is a Dropbox.File.Stat instance describing the removed file or folder, and the first parameter is null

The method treats String arguments as paths and CopyReference instances as
copy references. The CopyReference constructor can be used to get instances
out of copy reference strings, or out of their JSON representations.

called with the result of the /fileops/copy HTTP request; if the call succeeds, the second parameter is a Dropbox.File.Stat instance describing the file or folder created by the copy operation, and the first parameter is null

Returns

the XHR object used for this API call

XMLHttpRequest move(fromPath, toPath, callback)

Moves a file or folder to a different location in a user's Dropbox.

Parameters

fromPath
(String)

the path of the file or folder that will be moved, relative to the user's Dropbox or to the application's folder

toPath
(String)

the path that the file or folder will have after the method call; the path is relative to the user's Dropbox or to the application's folder

called with the result of the /fileops/move HTTP request; if the call succeeds, the second parameter is a Dropbox.File.Stat instance describing the moved file or folder at its new location, and the first parameter is null

Returns

the XHR object used for this API call

XMLHttpRequest appInfo(appKey, callback)

Fetches information about a Dropbox Platform application.

This method retrieves the same information that is displayed on the OAuth
authorize page, in a machine-friendly format. It is intended to be used in
IDEs and debugging.

Parameters

appKey
(String)

(optional) the App key of the application whose information will be retrieved; if not given, the App key passed to this Client will be used instead

called with the result of the /app/info HTTP request; if the call succeeds, the second parameter is a Dropbox.Http.AppInfo instance describing the application whose key was given

Returns

the XHR object used for this API call

XMLHttpRequest isAppDeveloper(userId, appKey, callback)

Checks if a user is a developer for a Dropbox Platform application.

This is intended to be used by IDEs to validate Dropbox App keys that their
users input. This method can be used to make sure that users go to
/developers and generate their own App keys, instead of copy-pasting keys
from code samples. The metod can also be used to enable debugging / logging
in applications.

called with the result of the /app/check_developer HTTP request; if the call succeeds, the second argument will be true if the user with the given ID is a developer of the given application, and false otherwise

Returns

the XHR object used for this API call

XMLHttpRequest hasOauthRedirectUri(redirectUri, appKey, callback)

Checks if a given URI is an OAuth redirect URI for a Dropbox application.

This is intended to be used in IDEs and debugging. The same information can
be obtained by checking the HTTP status in an /oauth2/authorize HTTP GET
with request_uri set to the desired URI.

Parameters

redirectUri
(String)

the URI that will be checked against the app's list of allowed OAuth redirect URIs

called with the result of the /app/check_redirect_uri HTTP request; if the call succeeds, the second argument will be true if the given URI is on the application's list of allowed OAuth redirect URIs, and false otherwise

Returns

Dropbox.Client#signOut should be called when the user expresses an intent
to sign off the application. This method resets user-related fields from
the Client instance, but does not work with the OAuth driver to do a full
sign out. For example, the user's OAuth 2 access token might remain in
localStorage.

Returns

Properties

fires cancelable events every time when a network request to the Dropbox API server is about to be sent; if the event is canceled by returning a falsey value from a listener, the network request is silently discarded; whenever possible, listeners should restrict themselves to using the xhr property of the Dropbox.Util.Xhr instance passed to them; everything else in the Dropbox.Util.Xhr API is in flux

Returns

See Also

The redirect URL that should be supplied to the OAuth 2 /authorize call.

The driver must be able to intercept redirects to the returned URL and
extract the OAuth 2.0 authorization code or access token from the URL.

OAuth 2.0 redirect URLs must be configured on the application's page in
the Dropbox App console.

Returns

an URL on the application's list of OAuth 2 redirect URLs

void doAuthorize(authUrl, stateParam, client, callback)

Redirects users to /authorize and waits for them to get redirected back.

This method is called when the OAuth 2 process reaches the
Dropbox.Client.PARAM_SET step, meaning that the user must be shown an
/authorize page on the Dropbox servers, and the application must intercept
a redirect from that page. The redirect URL contains an OAuth 2
authorization code or access token.

Parameters

authUrl
(String)

the URL that users should be sent to in order to authorize the application's token; this points to a webpage on Dropbox's server

stateParam
(String)

the nonce sent as the OAuth 2 state parameter; the Dropbox Web server will echo this nonce in the 'state' query parameter when redirecting users to the URL returned by Dropbox.AuthDriver#url; the driver should silently ignore any request that does not contain the correct 'state' parameter value

called when users have completed the authorization flow; the driver should call this when Dropbox redirects users to the URL returned by the url() method, and the "state" query parameter matches the value passed in "state"; the callback should receive the query parameters in the redirect URL

Server-side drivers should provide custom implementations that use a
derivative of the CSRF token associated with the user's session cookie.
This prevents CSRF attacks that would trick the application's server into
using an attacker's OAuth 2 access token to store anoher user's data in the
attacker's Dropbox.

Client-side drivers only need to supply a custom implementation if the
state parameter must be persisted across page reloads, e.g. if the
authorization is done via redirects.

Parameters

called with the state parameter value that should be used in the OAuth 2 authorization process

void resumeAuthorize(stateParam, client, callback)

(optional) Called to process the /authorize redirect.

This method is called when the OAuth 2 process reaches the
Dropbox.Client.PARAM_LOADED step, meaning that an OAuth 2 state parameter
value was loaded when the Dropbox.Client object was constructed, or during
a Dropbox.Client#setCredentials call. This means that
Dropbox.AuthDriver#doAuthorize was called earlier, saved that state
parameter, and did not complete the OAuth 2 process. This happens when the
OAuth 2 process requires page reloads, e.g. if the authorization is done
via redirects.

Parameters

stateParam
(String)

the nonce sent as the OAuth 2 state parameter; the Dropbox Web server will echo this nonce in the 'state' query parameter when redirecting users to the URL returned by Dropbox.AuthDriver#url; the driver should silently ignore any request that does not contain the correct 'state' parameter value

called when the user has completed the authorization flow; the driver should call this when Dropbox redirects the user to the URL returned by Dropbox.AuthDriver#url, and the "state" query parameter matches the value passed in "state"; the callback should receive the query parameters in the redirect URL

void onAuthStateChange(client, callback)

If defined, called when there is some progress in the OAuth 2 process.

The OAuth process goes through the following states:

Dropbox.Client.RESET - the client has no OAuth credentials, and is about to ask for an authorization code or access token

Dropbox.Client.AUTHORIZED - the client has an authorization code, and is about to exchange it for an access token

Dropbox.Client.DONE - the client has an OAuth 2 access token that can be used for all API calls; the OAuth 2 process is complete, and the callback passed to authorize is about to be called

Dropbox.Client.SIGNED_OUT - the client's Dropbox.Client#signOut() was called, and the client's OAuth 2 access token was invalidated

Dropbox.Client.ERROR - the client encounered an error during the OAuth 2 process; the callback passed to authorize is about to be called with the error information

Status value indicating that the server received a conflicting update.

This is used by some backend methods to indicate that the client needs to
download server-side changes and perform conflict resolution. Under normal
usage, errors with this code should never surface to the code using
dropbox.js.

RATE_LIMITED

Status value indicating that the application is making too many requests.

Rate-limiting can happen on a per-application or per-user basis.

SERVER_ERROR

Status value indicating a server issue.

The request should be retried after some time.

OVER_QUOTA

Status value indicating that the user's Dropbox is over its storage quota.

The application UI should communicate to the user that their data cannot be
stored in Dropbox.

Dropbox.Datastore

Synchronization happens at the datastore scope, so only records that are in
the same datastore can be changed together in an atomic fashion.

Access control also happens at the datastore scope, so users can
create datastores that can be shared with other users. Datastores
are shared by assigning roles (owner, editor, viewer, or none) to
principals (public or team, the latter if the account is a Dropbox
for business (DfB) account). Any account with the correct permissions
will be able to open the datastore by ID.

Class Methods

Number int64(x)

A Number instance that will be written to the datastore as a
64-bit integer.

Since JavaScript does not support 64-bit integers natively, an
int64 is a boxed JavaScript number that approximates the
64-bit integer as closely as possible, with an added property
dbxInt64 that holds the precise signed integer value in
decimal representation as a string. For integers that are at most
2^53 in magnitude, the approximation is exact.

Parameters

x
(String, Number)

an integer, a string holding a signed 64-bit integer in decimal representation, or the return value of a Dropbox.Datastore.int64 call

Returns

True if this datastore is shareable, false otherwise

String getEffectiveRole()

Gets the effective role of this datastore. This indicates the
current user's access level. The OWNER and EDITOR roles give full
control (reading, writing, changing roles); the VIEWER role gives
read-only control. The OWNER role is established at datastore
creation and cannot be changed. For non-shareable (private)
datastores OWNER is the only role.

Returns

the role of this datastore; OWNER, EDITOR, VIEWER, NONE (but NONE should never occur; always OWNER for private datastores)

Returns

Parameters

tableId
(String)

the table's ID

Returns

a Table object that can be used to insert or access records in the table with the given ID. If this is a new table ID, the table will not be visible in Dropbox.Datastore#listTableIds until a record is inserted.

Returns

The overall size of a datastore is calculated by summing the size of all
records, plus the base size of an empty datastore itself.

void close()

Closes the datastore.

After a call to Dropbox.Datastore#close, you can no longer call methods
that read or modify tables or records of the datastore.

The datastore will stop syncing once all outgoing changes have
been received by the server.

String getId()

Returns this datastore's ID.

Object getSyncStatus()

Returns an object representing the sync status of the datastore.

The returned object has a single property:

uploading: true if there are changes to the datastore that have not been synced to the server yet. This state should be transient unless, for example, the application is temporarily offline. false otherwise.

Returns

a plain object with an "uploading" property as described above

Properties

RECORD_COUNT_LIMIT (Number)

The maximum number of records in a datastore.

BASE_DATASTORE_SIZE (Number)

The size in bytes of a datastore before accounting for the size of its records.

The overall size of a datastore is this value plus the size of all records.

TEAM (String)

This principal refers to the DfB team of the datastore's owner.
This is only valid if the owner is a member of a DfB team.

Fires non-cancelable events every time a record changes, either
due to a local or remote change.

Note: Since this is fired for local datastore changes, making
further changes in the listener can lead to infinite loops. Use
Dropbox.Datastore.RecordsChanged#isLocal to determine if a
change was local or remote.

Dropbox.Datastore.DatastoreManager

Lets you open, create, delete, and list datastores.

Multiple instances of your app (running in different browser windows / tabs)
can open the same datastore at the same time, and a single instance of your
app can open multiple datastores at the same time. But a single instance of
your app can only have one Dropbox.Datastore instance for a each datastore
at any time -- opening the same datastore twice is not allowed (unless you
close it in between).

Class Methods

Boolean isValidId(tableId)

Checks that a string meets the constraints for table IDs.

Table IDs must be strings containing 1-64 characters from the set
a-z, A-Z, 0-9, dot (.), underscore (_), plus sign (+), minus sign
(-), equal sign (=), forward slash (/). The first character may
also be a colon (:), but such table IDs are reserved.

This character set accomodates base64-encoded strings, as well as URL-safe
base64-encoded strings.

Returns

Sets a resolution rule for conflicts involving the given field,
which will be used when automatically merging local and remote
changes. The rule applies to all records in this table, and any
previously-set rule for the same field of the same table is
replaced. The "remote" rule is used by default if no rule is set.

The valid rules are:

"remote": Resolves conflicts by selecting the remote change from the Dropbox server. This is the default conflict resolution rule.

"local": Resolves conflicts by selecting the local change on this client.

"max": Resolves conflicts by selecting the largest value, based on type-specific ordering.

"min": Resolves conflicts by selecting the smallest value, based on type-specific ordering.

"sum": Resolves conflicts by calculating a value such that all additions to or subtractions from a numerical value are preserved and combined. This allows a numerical value to act as a counter or accumulator without losing any updates. For non-numerical values this resolution rule behaves as "remote".

Rules are not persistent, so you should always set up any
non-default resolution rules before making any changes to your
datastore.

Parameters

fieldName
(String)

the field that the rule applies to

rule
(String)

one of "remote", "local", "min", "max", or "sum"

Returns

this, for easy call chaining

Dropbox.Datastore.Record

Stores key-value pairs.

Records belong to datastores, and are grouped into tables. Changes to records
in the same datastore can be synchronized atomically.

Record instances can be obtained by calling the methods defined in
Dropbox.Datastore.Table. Record objects should not be constructed directly.

Values of record fields are owned by the record and should not be
mutated directly, except for Lists, which can be mutated with the
List methods.

Class Methods

Boolean isValidId(recordId)

Checks that a string meets the constraints for record IDs.

Record IDs must be strings containing 1-64 characters from the set
a-z, A-Z, 0-9, dot (.), underscore (_), plus sign (+), minus sign
(-), equal sign (=), forward slash (/). The first character may
also be a colon (:), but such record IDs are reserved.

This character set accomodates base64-encoded strings, as well as URL-safe
base64-encoded strings.

The returned value can also be null, which indicates that
the specified field does not exist on this record.

Note that if the field holds a 64-bit integer, the return value
will be a boxed Number that approximates the 64-bit integer
as closely as possible, with an additional property dbxInt64
that holds the precise signed integer value in decimal
representation as a string (see Dropbox.Datastore.int64). For
integers that are at most 2^53 in magnitude, the approximation is
exact.

Parameters

Returns

A field can store a single value. This method discards the field's old
value. Future Dropbox.Datastore.Record#get calls will return the new value.

The value can be one of several native JavaScript types:

String

Number

Boolean

Date

Uint8Array

Array

Setting a value of null deletes the field from the record. Special
considerations apply to certain types:

Number: By default, a regular JavaScript number will be stored as a double for other platforms. To store the value instead as a 64-bit integer, use Dropbox.Datastore.int64 to create a boxed number.

Array: Each element of the array can be any of the supported types except Array. Elements of the array need not be of the same type. When this field value is retrieved using Dropbox.Datastore.Record#get, it will be returned as a Dropbox.Datastore.List.

Parameters

fieldName
(String)

the name of the field whose value will be modified

value
(String|Number|Boolean|Date|Uint8Array|Array|null)

the value to store in the field

Returns

Returns a Dropbox.Datastore.List from the given field of the
record, creating an empty one if the field does not currently
exist on this record. An error is thrown if the field exists but
contains a value that is not a Dropbox.Datastore.List.

Returns

The association between a record and its table is established when the
record is created. Records cannot be moved between tables.

Returns

the table that this record belongs to

Boolean isDeleted()

Returns true if this record was deleted from the datastore

Returns

true if this record was deleted from the datastore

Properties

BASE_RECORD_SIZE (Number)

The size in bytes of a record before accounting for the sizes of its fields.

The overall size of a record is this value plus the sum of the sizes of its fields.

Constants

BASE_FIELD_SIZE

The size in bytes of a field before accounting for the sizes of its values.

The overall size of a field is this value plus:

For String and Uint8Array: the length in bytes of the value.

For Dropbox.Datastore.List: the sum of the size of each list item, where each item's size is computed as the size of the item value plus Dropbox.Datastore.List.BASE_ITEM_SIZE.

For other atomic types: no additional contribution to the size of the field.

Dropbox.Datastore.RecordsChanged

An event indicating an update to a set of records.

RecordsChanged events are fired for changes that this instance
of the app made locally as well as for changes synced from other
(remote) instances of the app. Use
Dropbox.Datastore.RecordsChanged#isLocal to tell the difference.

Each list element can be a String, Boolean, Number
(including Dropbox.Datastore.int64), Date, or
Uint8Array. Lists can mix elements of different types.

Modifications of the list will result in modifications of the
datastore record field where the list is stored.

List elements are owned by the list and should not be mutated.

Whenever a method takes an index argument, negative numbers count
from the end of the list.

Instance Methods

String|Number|Boolean|Date|Uint8Array get(index)

Returns the list element at index.

Parameters

index
(Number)

void set(index, value)

Sets the list element at index to value.

Parameters

index
(Number)

value
(String|Number|Boolean|Date|Uint8Array)

Number length()

Returns the number of elements in the list.

Returns

the length of the list

String|Number|Boolean|Date|Uint8Array pop()

Like Array.pop, removes the last element from the list and
returns it.

Returns

the element that was removed

void push(value)

Like Array.push, appends the given value to the end of the list.

Parameters

value
(String|Number|Boolean|Date|Uint8Array)

String|Number|Boolean|Date|Uint8Array shift()

Like Array.shift, removes the first element from the list
and returns it.

Returns

the element that was removed

void unshift(value)

Like Array.unshift, inserts the given value at the beginning of the list.

Parameters

value
(String|Number|Boolean|Date|Uint8Array)

the value to insert

Array<String|Number|Boolean|Date|Uint8Array> splice(index, howMany)

Like Array.splice, removes howMany consecutive
elements from the list starting at index, then inserts
elements (if any) at index.

Parameters

index
(Number)

howMany
(Number)

the number of elements to remove

Returns

the removed elements as an Array

void move(oldIndex, newIndex)

Moves the element at oldIndex to position newIndex.

This is similar to removing an element from oldIndex, then
inserting it at newIndex, except that this is expressed as a
"move" operation for conflict resolution, which means it won't
result in duplicate elements like a removal and insertion would.

After the move, the element formerly at oldIndex will be at
newIndex.

This method does nothing if oldIndex and newIndex are
the same.

Parameters

oldIndex
(Number)

newIndex
(Number)

String|Number|Boolean|Date|Uint8Array remove(index)

Removes the element at index and returns it.

Elements with indexes greater than index are shifted to the
left.

Parameters

index
(Number)

Returns

the removed element

void insert(index, value)

Inserts the given value at index.

Elements with indexes greater than or equal to index are
shifted to the right.

Parameters

index
(Number)

value
(String|Number|Boolean|Date|Uint8Array)

Array<String|Number|Boolean|Date|Uint8Array> slice(from, to)

Returns an array that contains the elements of this list between
from (inclusive) and to (exclusive).

The returned array is a copy, so the elements will not update as
changes are applied.

Parameters

from
(Number)

to
(Number)

Array<String|Number|Boolean|Date|Uint8Array> toArray()

Returns an array with the same elements as this list.

The returned array is a copy, so the elements will not update as
changes are applied.

Constants

BASE_ITEM_SIZE

The size in bytes of a list item.

The overall size of a list item is this value plus the size of the item value.

an identifier for the contents of the described file or directories; this can used to restore a file's contents to a previous version, or to save bandwidth by not retrieving the same folder contents twice

contentHash (String)

A hash over the folder's contents; this can be used to save
bandwidth when repeatedly reading a directory's content.

mimeType (String)

a guess of the MIME type representing the file or folder's contents

size (Number)

the size of the file, in bytes; null for folders

humanSize (String)

the size of the file, in a human-readable format, such as "225.4KB"; the format of this string is influenced by the API client's locale

hasThumbnail (Boolean)

if false, the URL generated by thumbnailUrl does not point to a valid image, and should not be used

modifiedAt (Date)

the file or folder's last modification time

clientModifiedAt (Date)

the file or folder's last modification time, as reported by the Dropbox client that uploaded the file; this time should not be trusted, but can be used for UI (display, sorting); this is null if the server does not report any time

Dropbox.File.CopyReference

Reference to a file that can be used to make a copy across users' Dropboxes.

See Also

Dropbox.AuthDriver.ChromeExtension

OAuth driver code specific to Chrome extensions.

Class Methods

void oauthReceiver()

Communicates with the driver from the OAuth receiver page.

The easiest way for a Chrome extension to keep up to date with dropbox.js
is to set up a popup receiver page that loads dropbox.js and calls this
method. This guarantees that the code used to communicate between the popup
receiver page and Dropbox.AuthDriver.ChromeExtension#doAuthorize stays up
to date as dropbox.js is updated.

Instance Methods

constructor(options)

Sets up an OAuth driver for a Chrome extension.

Parameters

options
(Object)

(optional) one or more of the options below

Options parameter

scope (String)

embedded in the chrome.storage.local key that holds the authentication data; useful for having multiple OAuth tokens in a single application

receiverPath (String)

the path of page that receives the /authorize redirect and calls Dropbox.AuthDriver.Chrome.oauthReceiver; the path should be relative to the extension folder; by default, it is 'chrome_oauth_receiver.html'

void doAuthorize()

Shows the authorization URL in a new tab, waits for it to send a message.

See Also

See Also

Dropbox.AuthDriver.NodeServer

OAuth driver that redirects the browser to a node app to complete the flow.

This is useful for testing node.js libraries and applications.

Instance Methods

constructor(options)

Starts up the node app that intercepts the browser redirect.

Parameters

options
(Object)

(optional) one or more of the options below

Options parameter

port (Number)

the number of the TCP port that will receive HTTPS requests; defaults to 8912

tls (Object)

one or more of the options accepted by tls.createServer in the node.js standard library; at a minimum, the key option should be provided

void authType()

The /authorize response type.

void url()

URL to the node.js OAuth callback handler.

void doAuthorize()

Opens the token

void openBrowser()

Opens the given URL in a browser.

void createApp()

Creates and starts up an HTTP server that will intercept the redirect.

void closeServer()

Shuts down the HTTP server.

The driver will become unusable after this call.

void doRequest()

Reads out an /authorize callback.

void closeBrowser()

Renders a response that will close the browser window used for OAuth.

Dropbox.AuthDriver.Popup

OAuth driver that uses a popup window and postMessage to complete the flow.

Class Methods

String locationOrigin(location)

The origin of a location, in the context of the same-origin policy.

Parameters

location
(String)

the URL whose origin is computed

Returns

the location's origin

void oauthReceiver()

Communicates with the driver from the OAuth receiver page.

The easiest way for an application to keep up to date with dropbox.js is to
set up a popup receiver page that loads dropbox.js and calls this method.
This guarantees that the code used to communicate between the popup
receiver page and Dropbox.AuthDriver.Popup#doAuthorize stays up to date
as dropbox.js is updated.

Instance Methods

constructor(options)

Sets up a popup-based OAuth driver.

Parameters

options
(Object)

(optional) one or more of the options below

Options parameter

receiverUrl (String)

URL to the page that receives the /authorize redirect and performs the postMessage

receiverFile (String)

the URL to the receiver page will be computed by replacing the file name (everything after the last /) of the current location with this parameter's value

scope (String)

embedded in the localStorage key that holds the authentication data; useful for having multiple OAuth tokens in a single application

rememberUser (Boolean)

if false, the user's OAuth tokens are not saved in localStorage; true by default

String url()

URL of the redirect receiver page, which posts a message back to this page.

Class Methods

Parameters

Returns

a PulledChange instance wrapping the given entry of a /delta API call response

Properties

path (String)

the path of the changed file or folder

wasRemoved (Boolean)

if true, this change is a deletion of the file or folder at the change's path; if a folder is deleted, all its contents (files and sub-folders) were also be deleted; pullChanges might not return separate changes expressing for the files or sub-folders

Returns

Instance Methods

Returns

an ASCII string that can be passed to pullChanges instead of this PulledChanges instance

Properties

blankSlate (Boolean)

if true, the application should reset its copy of the user's Dropbox before applying the changes described by this instance

cursorTag (String)

encodes a cursor in the list of changes to a user's Dropbox; a pullChanges call returns some changes at the cursor, and then advance the cursor to account for the returned changes; the new cursor is returned by pullChanges, and meant to be used by a subsequent pullChanges call

shouldPullAgain (Boolean)

if true, the pullChanges call returned a subset of the available changes, and the application should repeat the call immediately to get more changes

shouldBackOff (Boolean)

if true, the API call will not have any more changes available in the nearby future, so the application should wait for at least 5 minutes before issuing another pullChanges request

This is a simplified version of the addEventListener DOM API. Listeners
must be functions, and they can be removed by calling removeListener.

This method is idempotent, so a function will not be added to the list of
listeners if was previously added.

Parameters

listener
(function(Object))

called every time an event is fired; if the event is cancelable, the function can return false to cancel the event, or any other value to allow it to propagate; the return value is ignored for non-cancelable events

Parameters

called when the XMLHttpRequest completes; if an error occurs, the first parameter will be a Dropbox.ApiError; otherwise, the first parameter will be null, the second parameter will be an instance of the required response type (e.g., String, Blob), the third parameter will be the JSON-parsed 'x-dropbox-metadata' header, and the fourth parameter will be an object containing all the headers

Returns

The OAuth signature will become invalid if the parameters are changed after
the signing process.

This method automatically decides the best way to add the OAuth signature
to the current request. Modifying the request in any way (e.g., by adding
headers) might result in a valid signature that is applied in a sub-optimal
fashion. For best results, call this right before Dropbox.Util.Xhr#prepare.

This method completely sets up a native XHR object and stops short of
calling its send() method, so the API client has a chance of customizing
the XHR. After customizing the XHR, Dropbox.Util.Xhr#send should be
called.

Parameters

called when the XHR completes; if an error occurs, the first parameter will be a Dropbox.ApiError instance; otherwise, the second parameter will be an instance of the required response type (e.g., String, Blob), and the third parameter will be the JSON-parsed 'x-dropbox-metadata' header