Core API version 0 migration guide

Version 0 of the Core API is deprecated and access to it is restricted. It's important that you migrate your apps to version 1 so that your Dropbox integration continues to work properly.

Timeline

  • October 11, 2011 - Announced version 1 of the Core API, deprecating version 0.
  • August 17, 2012 - Announced version 0 shut down on December 1, 2012.
  • December 1, 2012 - Extended to March 4, 2013 to give developers more time to migrate and users time to upgrade their apps if necessary.
  • March 4, 2013 - Restrict access to version 0 to existing users. No new users will be able to link to apps using version 0 of the API.
  • May 1, 2013 - Shut down version 0.

Major changes

Much of the functionality within version 0 remains unchanged in version 1. However, there are some changes to be aware of while migrating, the most important of which is the required OAuth authentication flow.

SDKs

  • SDKs for iOS, Java/Android, Python, and Ruby were released with version 1. These packages extends the existing REST API by including easy-to-use and well-documented libraries as well as example code. Downloading an SDK is highly recommended.
  • V1 requires OAuth, which handles user credentials more securely and authenticates via official Dropbox apps (if installed on a user's device) or the Dropbox website. /token is no longer supported.
  • It's no longer necessary for apps to provide their own account creation flow. Users without Dropbox accounts will be prompted to create one as part of the new OAuth flow.

API calls

New features

  • New methods: /search, /delta, /copy_ref, /chunked_upload, /revisions, and /restore.
  • /thumbnail supports new, larger, sizes.
  • A new application-specific folder permission permits secure, more granular control of your users' Dropbox.
  • Responses now include a rev value for easy tracking of file or folder revisions.

Revisions and modifications

  • Authentication is done via OAuth instead of the username/password mechanism.
  • All calls are required to use HTTPS.
  • /links and /streams have been replaced with /shares and /media respectively.
  • Calls no longer accept the callback and status_in_response parameters.
  • /files_put is the recommended way for uploading files (though POST to /files is backwards compatible).

Authentication

Except where mentioned above, most V1 functionality essentially mirrors V0. The greatest difference in integration is the authentication flow; namely, integrating OAuth into your app. For a top-level view of how this works, see the Dropbox authentication tutorial. For more concrete examples, see the code samples included with the SDKs. For questions and best practices, take a look at this recent developer blog post. In most cases, all you have to do is migrate the example code using your app's authentication keys to your app. Everything else, including user login and authorization, is taken care of by the official Dropbox apps or the Dropbox website.

Steps to migrate

  1. There's no need to modify your app in the Apps section of the Developers website. Your app is automatically grandfathered into Full Dropbox access. You will need to obtain your app keys from the options page of your app to create your OAuth tokens.
  2. If you're considering using an SDK, you can download the latest versions from the developer kits page. In many ways, the SDKs are the easiest way to interact with the Dropbox API, particularly in respect to authentication and advanced file operations unique to the platform of your choice.
  3. Migrate authentication from /token to OAuth. Visit the authentication tutorial for instructions. For specific examples, view the example code in the SDK of your choice.
  4. Point all endpoint paths to version 1. For example: https://api.dropbox.com/0/fileops/create_folder becomes https://api.dropbox.com/1/fileops/create_folder
  5. Remove all references to the callback and status_in_response parameters.
  6. Remove references to calls made obsolete by V1:

Most file operations, including /files_put, will automatically return metadata information upon successful operation. You may want to prepare your app to handle this information appropriately.

Further questions

In many cases, migrating applications should be straightforward. But we recognize that some applications are doing unique things with the API. If you need help with moving to V1 of the API or 1.* series SDKs, please see the developer forum or contact api-migration@dropbox.com.