Dropbox REST API mostly using POST

Gian-Luca Z.

Hi there,

from the Blog entry about the new API:

"Overall, we’ve simplified our use of HTTP. For example, most endpoints always use HTTP POST, including those that return structured data."

I was wondering, what is the benefit of using one verb (POST) for mostly all calls? I know that you can describe DELETE and PUT/PATCH calls with POST (which is done on some servers because they can't handle those), but why would it be better to get rid of GET and make it POST calls?

Can someone explain me this design decision?

Thank you

Steve M.

Gian-Luca, thanks for asking this! The way our team has been thinking about API v2 is that we want to make the API as simple as possible. In this case, that means using fewer HTTP verbs. Looking at the question from a different angle, what are the advantages of using GET? Here are a few possibilities:

1. GET is more friendly to caches. (POST responses may be cached, but in practice I believe caching of GET responses is better supported.) For the RPC-style endpoints, we actually don't want caching anyway, so this wouldn't benefit us.
2. GET is guaranteed to be idempotent. This makes GET requests safe to retry, which is not the case for POST. In practice, I'm not sure how much this matters. Automatic retries are rare outside the context of an SDK, where the author can decide which things to retry based on the endpoint and the response.
3. GET is simply what developers expect to see for API calls that retrieve data without side-effects.

POST—and other verbs that carry a request body—have their own advantages. Notably, the body can carry data of any size and with any encoding. In API v2, we're planning on using JSON for everything. See also https://blogs.dropbox.com/developers/2015/03/limitations-of-the-get-method-in-http/ for a discussion of where we ran into size limits on GET requests when building API v1.

Note that we support GET for download-style endpoints, where we do want to make sure browsers can cache the server response. When we use GET, we use JSON-encoded parameters in a header.

Do you have other reasons for why you'd prefer GET? The primary reason for sharing the API v2 preview is to collect this sort of feedback and make improvements as needed, so thank you for sharing your thoughts!

P.S. I have to correct you... you said "Dropbox REST API," but the API definitely isn't REST. :-)