Child Item

Requesting an API call to find revision by date

I'm looking at the API documentation for /revisions, and it seems like it's missing a really obvious use case: finding the single revision closest to the specified date (or, the two revisions closest to the specified date on either side—that is, the latest revision before the specified date and the earliest revision after the specified date).

Suppose I knew I wanted to restore a file to the state it was on 2015-05-02 22:32 GMT. The only practical way to go about this is to fetch an increasingly large number of revisions with /revision (starting with 10, then 100, then 1000) until the oldest one is after the required date. That's a heck of a lot of work on Dropbox's end and a lot of bandwidth spent transferring data which is mostly useless to me, since I'm only looking for one or two revisions. And that might actually still be a failure, if there have been more than 1000 revisions since the date I'm trying to restore to.

Unless there's some better way to do that which I've missed, I'd like to suggest a new endpoint called, say, find_revision, which takes a path, a date, and a bool "after," and returns the revision number for the specified file for the revision closest to that date. If after is true, it looks for the closest revision after the specified date, otherwise it looks for the closest revision equal to or before. (Alternatively, you could simplify it to return both revisions, if they exist, and not bother with the additional bool param.)

Relatedly, though I don't actually need it myself, it might be useful for some developers to have an endpoint that takes a path and a revision number and returns the previous and next valid revision numbers.

Find more posts tagged with

API

Abuse

Comments

Greg-DB

You're correct, unfortunately the Dropbox API doesn't currently offer a way to query revisions by date, or retrieve more than 1,000 revisions, but I'll be sure to pass this along as feedback.

Daniel E.2

Thanks. My plan for now is to just use an incremental binary search (or whatever academic term there is for that) and maybe cache revision numbers and dates for files with unusually high update frequency, which may suffice but is still more work on my end (and more bandwidth and API requests on yours) than should really be necessary.

While you're passing this along, if I can add two more suggestions?

A more powerful way to fill this gap would be to add the optional date parameter to /metadata instead of /revisions, and have it return the metadata for the object at that point in time. (So, the metadata for the most recent revision of that object equal to or before the specified date.) And, for folders, with list=true, to also return the metadata of the contents at that point in time. This would also make it possible to get historical information about folders. As near as I can tell, the only way to determine if a folder was deleted on a particular date is to check if all of its children were deleted on the same timestamp, and that can't distinguish between a folder itself being deleted or all its contents being deleted simultaneously. More work to implement on your end, though, naturally.

And, secondly, you might consider adding the option to get a more minimal list of information from /revisions and /metadata. For the application I'm writing now, the vast majority of my calls to /revisions are only going to be looking for the revision number and date, and the vast majority of my calls to /metadata will be fore folders with list=true, but are only going to be looking for the paths, is_dir, and is_deleted values of the folder and contents. I suspect that's probably a common use case for those endpoints, and I'm guessing that mobile app developers would love to be able to save their users some unnecessary data transfer.

Steve M.

Daniel, all of your suggestions are good ones. Thanks.

As for what you should do now, why wouldn't you just always request 1000 (the max) revisions? Are you trying to speed the process up? Save bandwidth? Something else?

Daniel E.2

There's no reason on my end not to do it, I just didn't want to put undue strain on your service. I mean, obviously, even a fairly popular Dropbox app's API calls probably represent an infinitesimal fraction of the bandwidth you folks push out on a minutely basis--and I doubt what I'm writing now will be "fairly popular," even if I do let it escape into the wild--but I try my best to write well-behaved software when I can, particularly when it's going to be using someone else's services.

If it proves to be too complicated a solution to implement, I'll just give up and go hog wild with 1000-revision API calls, though, sure

Steve M.

If you end up making more than one call, I'm pretty sure that consumes more resources on the Dropbox side than if you had just requested all 1,000 in the first call.

Daniel E.2

Hmm, good point. It probably should've occurred to me that servicing the request is the expensive part, not actually transmitting the data. (In my defence, I've done very little back-end work--not really my area.) I guess I'll just set that more complicated plan aside until someone asks me to make a mobile version of this thing and I want to save them some data charges. And hey, maybe by then we'll have that new /metadata parameter!

Thanks for the info!

HaPsantran

Not only can't we query revisions by date, we can't query more than the most 100 recent revisions, period (as of v2). Major drawback if you update a file frequently and want to programmatically retrieve something alreadya availble in the web UI.

Greg-DB

@HaPsantran Thanks for the feedback!