A look at Dropbox API v2

Dropbox has been working on a new version of its API, and has now published a preview implementation of five core endpoints. The preview is meant to highlight the structural changes coming in v2, and to gather developer feedback before the API is finalized.

Simplified HTTP conventions

The most visible change in API v2 is a reduced reliance on the nuances of the HTTP spec. Most endpoints now always use HTTP POST — even those that return structured data — with JSON in both the request and response bodies.

HTTP GET is used only for endpoints that return bulk binary data, such as file downloads. These endpoints also support ETag-based caching, letting browsers and HTTP client libraries transparently cache file contents.

Error handling is also been made more uniform. Broad categories of failures still map to the same status codes as before: 400 for a bad request, 401 for authorization failure, 429 for rate limiting, and so on. However, where v1 used a variety of status codes — 403, 404, 406, 411 and others — to describe call-specific failures, v2 now always uses a 409 status code. The specific error is provided in the response body with a stable, documented identifier. The choice of 409 is deliberate: since it has no particular meaning defined in the HTTP spec, proxies and HTTP libraries will typically pass it through untouched rather than trying to interpret it.

Dropping the old version of the API also gives Dropbox a chance to retire legacy features, such as OAuth 1.0 support. OAuth 2 access tokens are required for API v2 calls.

Three endpoint styles

The five preview endpoints fall into three categories:

  • RPC-style: both request and response bodies are JSON.
  • Upload-style: metadata is passed as JSON in the Dropbox-API-Arg header, with bulk binary data in the request body. The response body is JSON.
  • Download-style: uses the GET method, with JSON in the Dropbox-API-Arg header and no request body. The response includes JSON in the Dropbox-API-Result header and binary data in the body.

Try the preview

The following endpoints are available for testing now: users/get_current_account, files/get_metadata, files/upload, and files/download. You can call them with an OAuth 2 token using Dropbox's Python REPL script, the Paw REST client for Mac (using Dropbox's Paw configuration file), or any other HTTP client. The files/upload endpoint is currently limited to files up to 150 MB; chunked upload endpoints for larger files are planned.

Dropbox warns that these APIs are beta and subject to change, and asks developers not to use them in production yet. Feedback can be shared in the comments section below or on the developer forum.