Core API best practices

User authorization

Never handle user login and password information. All application authentication should be completed using the OAuth. Each offical SDK has an approved implementation of OAuth and you should use one of these in your app if possible.

Handling revoked access

Your app should take precautions in case of revoked access. Access tokens may be disabled by the user (from the account page), revoked by Dropbox administrators in cases of abuse, or simply expire over time.

In the case where a token is no longer authorized, the REST API will return an HTTP Error 401 Unauthorized response. The iOS SDK detects 401s for you and will call the sessionDidReceiveAuthorizationFailure: method on the session's delegate to notify you that the authorization was revoked. The Android, Python, Ruby, and Java SDKs will all raise an exception on server errors that you can catch and inspect. Re-authenticating is typically all that is necessary to regain access.

Efficiency

Don't recursively troll the metadata to build your directory UI on startup. Instead, only get the directory the user is viewing, and do some caching so you don't have to ask constantly.
Use the hash parameter on metadata calls using the previous hash returned so that it returns a shorter list. metadata will give you a 304 if a hash matches and will return the contents again if the hash is different.
Don't download anything until the user has actually asked for it. Keep the hash we give you in the rev entry from the metadata response for the file. Compare rev entries to a fresh metadata call to see if you need to pull the file again or use /delta for a list of instructions to get your local state to match Dropbox's remote state.

Case insensitivity

A common thing that trips up new developers is that the Dropbox "file system" is case-insensitive, meaning that A/B/c.txt is the same file as a/b/C.txt and is the same file as a/B/c.txt.

This has also caused problems for developers who store file metadata from users in embedded databases (such as SQLite). Postgres is another database that is case sensitive and will cause problems. Case insensitive collations should be used when storing Dropbox metadata in these databases. Alternatively, developers need to make sure their query operators are explicitly case insensitive.

Rate limiting

The API limits the amount of calls your app can make per user. The limits are high enough that any reasonable use of the APIs shouldn't come close to hitting them. Apps that hit the rate limits will receive a 503 error which uses the Retry-After header to indicate exactly when it's okay to start making requests again. If your app uses OAuth 2.0, the error will be a 429 instead. If you keep hitting these limits, contact our developer support team and we'll work with you.