The second version of the popular file storage service contains a number of changes, including:
- Use of HTTP POST for most endpoints. Exceptions include endpoints that return bulk binary data and reasonably require caching.
- Modified use of HTTP status codes for certain errors. For requests that fail due to a call-specific issue, the Dropbox API v2 will always produce a 409 status code with more detail in the response body. Previously, similar failed requests could produce a variety of 4xx status code.
- Deprecation of OAuth 1.0 support. The v2 API will require use of OAuth 2.0.
Dropbox has made several v2 endpoints available for developers to experiment with. There are three kinds of endpoints: RPC-style endpoints where the request and response bodies are JSON, upload-style endpoints where bulk binary data is sent in the request and a JSON response is produced, and download-style endpoints where the GET method is used and the response body contains bulk binary data.
More API Design Controversy
Dropbox's decision to use HTTP POST widely, even for API requests that don't affect state, has been a controversial one, and the company's decision to use the 409 HTTP status code as a catch-all for certain types of errors could be criticized as well.
As Dropbox sees it, the use of 4xx status codes can create confusion, and using 409 as a catch-all simplifies life for developers. As Dropbox explained, "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."
But the 409 status code does have a specific meaning according to the HTTP spec, so it's not clear why Dropbox believes it doesn't. This notwithstanding, some might argue that, even though there is often reason to debate which status code is most appropriate for any given response, opting to use a single status code as a catch-all for errors that are call-specific defeats the entire purpose of status codes. Yes, Dropbox is returning error information in the response body, but if every API provider decided to take this approach, clients would not be able to use standard status codes to determine the likely cause of a failure.
Does simplicity justify Dropbox's decisions to eschew best practices around standard HTTP Methods and status codes? Let us know your thoughts in the comments.