Change feed

The change feed lists each file that changed since a token, as the caller sees it, so a sync client can keep a local copy current without listing the whole Drive.

A sync client takes a start token first, lists what is already there with files.list, then polls changes.list from the saved token and keeps the token each answer hands back. Taking the token first means no write between the list and the token goes unseen:

AUTH='Authorization: Bearer ya29.placeholder'
TOKEN=$(curl -s -H "$AUTH" "$RYSTIC_URL/drive/v3/changes/startPageToken" | jq -r .startPageToken)
curl -s -H "$AUTH" -H 'Content-Type: application/json' -X PATCH -d '{"name":"beach-sunrise-v2.jpg"}' "$RYSTIC_URL/drive/v3/files/1MVjpgBeachSunrise03?fields=id,name" | jq -c .
# -> {"id":"1MVjpgBeachSunrise03","name":"beach-sunrise-v2.jpg"}
curl -s -H "$AUTH" "$RYSTIC_URL/drive/v3/changes?pageToken=$TOKEN" | jq -c '{newStartPageToken, changes: [.changes[] | {fileId, removed, name: .file.name}]}'
# -> {"newStartPageToken":"24","changes":[{"fileId":"1MVjpgBeachSunrise03","removed":false,"name":"beach-sunrise-v2.jpg"}]}

One entry per file

A file created, renamed, moved, uploaded to, trashed, shared or unshared is listed once, holding its state when the page is read, however many times it changed since the token. A file the caller can no longer read, because it was deleted or unshared, is listed as removed: true with no file. A grant on a folder lists every file below it. Each caller’s feed holds only what that caller can read: X-Rystic-Actor picks the caller (Auth).

Pages

pageSize takes 1 to 1000 and defaults to 100; a value outside that range answers 400 invalidParameter at page_size. A page with more results carries nextPageToken: poll it next. The last page carries newStartPageToken instead: keep it and poll from it next time. Pick the next token by which member is present, not by how many entries came back. A request with no pageToken answers 400 required, and a token that is not a positive number 400 invalid.

Timing and tokens

The simulator lists a change as soon as its write answers, where Drive lists it 1 to 4 seconds later, so a client that polls once right after a write passes here and can miss the change on Drive. Retry for a few seconds when you test against Drive.

Tokens count the simulator’s own changes and keep counting across a reset or a scenario load, so a token never repeats and an older one lists only the changes made since. Treat a token as opaque and take it from startPageToken or newStartPageToken. A scenario’s seeded files are not in the feed: take a start token, list them with files.list, then poll from the token.

Push notifications are not served: changes.watch, files.watch and channels.stop send to an address you register, so poll instead.