Handling of local and remote rev differences

Question

Hello, I would like to ask for some confirmations and clarifications on syncing dropbox files with API v2.
I think I have uploading, downloading and listening for changes mostly figured out.
My problem is proper handling of the scenario where a local file has changed and is scheduled to be uploaded to dropbox through filesUpload, but the remote file has also changed due to a different instance of my app.
I (think I) understand that the correct method to determine that the remote file has changed is by storing the rev value on each download, then check if that rev is still the same before uploading. If local and remote rev differ, the remote file has changed without the local app noticing it until now. In my case, I would ask the user at this point which file he would like to overwrite:

Download the remote file, overwrite local or
upload the local file, overwrite the remote?
(I leave aside here more sophisticated approaches ie creating a “conflicted copy” file or presenting a diff to the user etc.)

Question 1:
Does that workflow above make sense? Are there scenarios I did not consider?

Question 2:
How would I roughly go about that workflow with the sdk endpoints?
I was weighing using files/list_folder/get_latest_cursor + files/list_folder/continue and checking the metadata before files/upload, but my feeling is that files/upload is still the “moment of truth” here, ie still possible that changes occured between checking the metadata from files/list_folder/continue and files/upload.

files/upload offers the write mode “update” with the local rev as parameter, but I read the documentation as stating that if the revs differ, the API will always create a conflicted copy file. I would rather cancel at this point and ask the user what to do, as described above.

Question 3:
Is there a way to configure files/upload with something like “if local rev and remote rev differ, throw an error and cancel filesUpload”?

Thank you very much for any reply!

Greg-DB · Accepted Answer

1. Yes, you're definitely on the right track here, and your description sounds right. There are a few extra pieces of functionality that you may want to be aware of too. First, while "rev" identifies a particular revision of a file, the Dropbox API also offers a "content hash" which is directly indicative of the actual contents of the file. You can find more information on that here.

There's also some other options around using the "rev" that I'll cover below as they address your other questions.

2. If you're only interested in changes going forward, you can use /2/files/list_folder/get_latest_cursor and /2/files/list_folder/continue like you said. Alternatively, if you want to start from a complete representation of the state of the account (or whatever folder you're interested in) though, you can instead start with /2/files/list_folder followed by /2/files/list_folder/continue as necessary to list everything.

Either way, you can then keep track of further changes by calling /2/files/list_folder/continue with the last returned cursor. Be sure to carefully read the /2/files/list_folder documentation for information on how to correctly process the returned entries.

(And for reference, those are links to the documentation for the HTTPS endpoints themselves, but we recommend using one of the official SDKs if possible, if you aren't already. Those have corresponding native methods for the HTTPS endpoints.)

Regardless, you're correct that you can check the current "rev" to see if the file has since changed, but that there is also inherently a race condition possible between when you last checked the metadata and when you actually perform an upload. For that reason, the "update" mode is generally the best and safest mode to use when continually updating an existing file. You can configure what Dropbox does when a conflict occurs though, as in your question 3.

3. Yes, when using the "update" write mode, if you set "autorename:false" (or omit the parameter entirely, as that's the default), Dropbox will automatically fail the upload request and return an error instead of committing a conflicted copy.

Hope this helps!