Cognite Data Fusion: Document Contract/Expectations of a Cursor Returned From The API

Thanks Ben! Will both create a ticket so we can update documentation / clarify, and respond with some answers after I’ve collected authoritative responses across the teams.

1. When a nextCursor value is returned from an API call, is this cursor value valid forever or does it expire?

Unless we change something in the api w.r.t content in the cursor, or encryption key, it is valid forever. Doesn’t store info like cluster, project or filter parameters. I.e. it’s “valid until it breaks”.

1. If it expires, how long is it guaranteed to be valid? (This documents part of the contract of the API.)

Doesn’t expire, but we’re considering the viability of making it time out (maybe an hour without accesses = let it expire ..?)

1. When we call an API subsequent times with the same parameters and provide a cursor value, are we getting data at the time of the current API call or cached data from the first time the API was called with those parameters?

Not using a cached copy of data so if you use a cursor but change the parameters, the API might serve data you’re not expecting.

1. If subsequent calls to the API with a cursor are NOT returning results of a cached copy and data has been inserted or deleted in the middle of the list while iterating through the cursors, is there any guarantee that data is not duplicated or skipped in the result sets returned?

A cursor is, largely speaking, an extra filter on the data so AFICT any inserted or deleted data that has achieved consistency should also be included.  With the caveat that a cursor only can move forward, so if the data is added/deleted from a page that’s “behind us” and the filter parameters remain the same, that added/deleted data should probably not show up in the context of those cursors.

I have updated https://docs.cognite.com/dev/concepts/pagination/ with a rephrased version of what Thomas wrote plus some further information.