A preview of the new Dropbox API v2

[EDIT June 3, 2015] This post has been updated to reflect the latest API v2 syntax.

We've been working on a new version of the Dropbox API for a while and it's time to show you what we have so far. To start, we've implemented a select set of endpoints that highlight the big structural changes underway, and we'd like to know what you think!

What's different?

Overall, we've simplified our use of HTTP. For example, most endpoints always use HTTP POST, including those that return structured data. Requests take JSON in the body and responses return JSON in the body.

We will continue to use other HTTP features in specific cases where they provide concrete benefits. For example, endpoints that return bulk binary data (e.g. file contents) support HTTP GET and ETag-based caching. This allows browsers and HTTP client libraries to transparently cache that data for you.

We've also simplified our use of HTTP status codes for errors. For errors that are common to all API calls, we do the same thing as before: 400 for bad request, 401 for auth failure, 429 for rate limiting, etc. But if a request fails for some call-specific reason, v1 might have returned any of 403, 404, 406, 411, etc. API v2 will always return a 409 status code with a stable and documented error identifier in the body. We chose 409 because, unlike many other error codes, it doesn't have any specific meaning in the HTTP spec. This ensures that HTTP intermediaries, such as proxies or client libraries, will relay it along untouched.

With these changes, we hope to make the Dropbox API easier to understand. We also hope to make it easier for developers to build apps and to create SDKs.

By releasing a new version of the API, we also have the ability to part ways with old, deprecated endpoints and response fields. For example, OAuth 1.0 is no longer supported in API v2. It's always nice to clean things up a bit!

Try it out!

We have five endpoints you can actually try out right now (see Endpoints below). You'll need an OAuth 2 access token to make API calls. If you don't have one already, it's easy to generate one for your own account.

To actually make the API calls, you have a few options:

Use our Python REPL script.
Use the Paw REST client app for Mac with our Paw configuration file. Replace "ACCESS_TOKEN" with your generated access token.
Use whatever you want! It's just HTTP.

Please remember that this is a beta version and things may change. Don't use these API endpoints in production yet. We're interested in your feedback, so let us know what you think in the comments or on our developer forum.

Endpoints

There are three categories of endpoints.

RPC-style: The request and response bodies are both JSON.
Upload-style: The request has JSON in the Dropbox-API-Arg header and bulk binary data in the body. The response body is JSON.
Download-style: The request uses the GET method and has JSON in the Dropbox-API-Arg header and nothing in the body. The response has JSON in the Dropbox-API-Result header and bulk binary data in the body.

users/get_current_account
(RPC-style)

Sample request:

curl -X POST <a class="vglnk" href="https://api.dropboxapi.com/2/users/get_current_account" rel="nofollow"><span>https</span><span>://</span><span>api</span><span>.</span><span>dropboxapi</span><span>.</span><span>com</span><span>/</span><span>2</span><span>/</span><span>users</span><span>/</span><span>get</span><span>_</span><span>current</span><span>_</span><span>account</span></a> \
    --header "Authorization: Bearer <access-token>" \
    --header "Content-Type: application/json" \
    --data "null"

Sample response:

200 OK
Content-Type: application/json
 
{
  "account_id": "dbid:AADjaKS0RWKMfS_-Tf88LFVeMUbWOlUjR9U",
  "name": {
    "given_name": "Panda",
    "surname": "Bamboo",
    "familiar_name": "Panda",
    "display_name": "Panda Bamboo"
  },
  "email": "panda@example.com",
  ...
}

files/get_metadata
(RPC-style)

Sample request:

curl -X POST <a class="vglnk" href="https://api.dropboxapi.com/2/files/list_folder" rel="nofollow"><span>https</span><span>://</span><span>api</span><span>.</span><span>dropboxapi</span><span>.</span><span>com</span><span>/</span><span>2</span><span>/</span><span>files</span><span>/</span><span>list</span><span>_</span><span>folder</span></a> \
    --header "Authorization: Bearer <access-token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\": \"\"}"

Sample response:

200 OK
Content-Type: application/json
 
{
  "cursor": "...",
  "entries": [
    {".tag": "file", "name": "cupcake.png", ... },
    {".tag": "folder", "name": "recipes", ... },
    {".tag": "file", "name": "ingredients.xlsx", ... },
    ...
  ],
  "has_more": false
}

files/upload
(upload-style)
Note that the upload file size is limited to 150 MB. New API endpoints for uploading larger files (in chunks) are coming soon.

Sample request:

200 OK
Content-Type: application/json
 
{
  "client_modified": "2015-03-26T21:31:57Z",
  "name": "cupcake.png",
  "path_lower": "/cupcake.png",
  "rev": "8e941b183490",
  "server_modified": "2015-03-26T21:31:57Z",
  "size": 59704
}

files/download
(download-style)

Sample request:

curl -X POST https://api.dropboxapi.com/2/files/get_metadata \ 
        --header "Authorization: Bearer <access-token>" \ 
        --header "Content-Type: application/json" \ --data "{\"path\": \"/cupcake.png\"}"

Sample response:

200 OK
Dropbox-API-Result: {"name": "cupcake.png",  ... }

// Tags

// Copy link

Link copied