Child Item

Dropbox Cursor Behavior

Hello,

I'm trying to confirm cursor behavior.

- Is it safe to assume that Cursor is an offset into a transaction log per account, which is a sequential record of changes as they occurred in the account. In other words, clients that traverse dropbox do not walk through their repository (i.e. the "tree" of content) looking for content; instead, the client enumerates changes sequentially as they occurred in Dropbox.

Find more posts tagged with

API

Abuse

Comments

DB-Des

Hi @mikirey,

The cursor value used for paginating through results is an encoded string that contains various pieces of information—such as the account ID, app ID, and parameters related to the original request.

The exact structure of the cursor is intentionally abstracted and may change over time, so we recommend treating it as an opaque value that's meant to be passed back to the API as-is, without modification or inspection.

mikirey

Thanks for your answer!

What I'm trying to understand is the consistent behavior of cursor as a pointer at a point in time. My use case is that instead of introducing the webhook complexity (leases, etc) into my application, I can just do a schedule scan every 15mins from the last cursor saved. If for some reason, during one of the scheduled scans, something failed. The next schedule can still pick up from the last cursor saved and we're not missing out on any updates.

Is this the correct understanding?
If during the scan, there are new files being uploaded/modified, these changes are appended, i.e. we can pick up those changes as the cursors progresses?
I've read some documentation indicating that cursors do become invalid after some time, do we have an approximate amount of time?

Thank you so much for your time!

DB-Des

@mikirey,

When you call /2/files/list_folder/get_latest_cursor, the Dropbox API will return a cursor for the corresponding account and path (if one is provided) at that particular point in time. So, if a call is made before any folder updates are done in that account, the cursor will be for "before" those latest additions.

Sending a request to /2/files/list_folder/continue with the cursor obtained from /2/files/list_folder/get_latest_cursor will return an empty "entries" array if no changes have occurred in the corresponding account or path (if one is provided) after that cursor was obtained.

A cursor could become invalid or stale over time. We don’t make any guarantees about how long a cursor remains valid, and we don’t have an approximate expiration window to share. Because of this, we recommend treating cursors as short-lived.

mikirey

Isn't this /2/files/list_folder/get_latest_cursor for polling in a continuous session and you cannot go backwards in time? My program is not limited to one continuous session; hence the approach is to save the cursor in a database for example, and then I can adjust my scan schedule.

Here is the snippet from Dropbox article, Detecting Changes.

Polling

As a result of this property of folder cursors, storing the cursor value allows you to poll for changes to the target directory. Folder cursors are long-lived, but may expire if unused for an extend time. Thus, while polling, be sure to always update to the latest returned cursor - even if no results are returned. A call to continue with an expired cursor will return a 409 reset error. This indicates you should issue a new call to /files/list_folder and iterate to obtain a new cursor. If the folder itself that the cursor refers to is deleted, the call will return a 409 path error. If your application is only interested in changes going forward, the /files/list_folder/get_latest_cursor will return the most recent cursor, without needing to iterate through list and continue calls.

DB-Des

@mikirey,

/2/files/list_folder/get_latest_cursor is a way to quickly get a cursor for the folder's state, and yes you cannot go backwards in time. The /2/files/list_folder/get_latest_cursor endpoint is for an app which only needs to know about new files and modifications and doesn't need to know about files that already exist in Dropbox.

Whereas /2/files/list_folder[continue] provides you with details about files and folders that exist in Dropbox.