Pagination and Delta Sync

Some flaik Connect endpoints come in pairs: a full pull for an initial load, and a delta pull for incremental sync afterwards. Both are paginated with the same cursor pattern, so once you understand one pair you understand them all.

Today this pattern applies to:

• Shift Data By Season

• Task Data By Season

This page is the shared reference for the cursor mechanics, the timestamp-boundary rules, and the recommended client loop. The endpoint pages cover what each record contains and what makes that endpoint specific — they link here for the rest.

Full pull vs delta pull

	Full pull	Delta pull
Route shape	GET …/{seasonId}	GET …/{seasonId}/delta
Use case	Initial load, complete re-sync	Ongoing incremental sync
updatedAfterUtcDateTime	Not accepted	Required
Soft-deleted records	Excluded	Included (so you can tombstone them)
Cursor	nextAfterId only	nextAfterId and nextUpdatedAfterUtcDateTime together

A typical client lifecycle is:

1. Run the full pull once to seed your store.

2. Record the timestamp at which you finished.

3. From then on, run the delta pull on a schedule, passing the last successful sync time.

Page size

Parameter	Type	Required	Description
pageSize	integer	No	Records per page. Default and maximum: 1000. Values outside 1–1000 are clamped.

Every paged endpoint returns at most pageSize records and tells you whether more remain via hasMore. There is no way to fetch more than 1,000 records in a single call.

The cursor

Every paged response includes the cursor for the next request, so clients don't need to inspect individual records.

Response field	Notes
hasMore	true if further pages exist for this query. Loop until this is false.
pageSize	The page size that was applied to this response.
nextAfterId	Pass this back as the nextAfterId query parameter on the next call. null when hasMore is false.
nextUpdatedAfterUtcDateTime	Delta pull only. Pass this back as updatedAfterUtcDateTime on the next call. null when hasMore is false.

Full pull — single-axis cursor

The full pull is ordered by record id and uses a single cursor: nextAfterId.

GET /api/schedule/tasks/18
  → hasMore: true,  nextAfterId: 1000,  data: [records 1–1000]

GET /api/schedule/tasks/18?nextAfterId=1000
  → hasMore: true,  nextAfterId: 2000,  data: [records 1001–2000]

GET /api/schedule/tasks/18?nextAfterId=2000
  → hasMore: false, nextAfterId: null,  data: [records 2001–2247]
  → Done

Delta pull — compound cursor

The delta pull is ordered by (updatedUtc, id) and uses both cursor fields. You must pass them together.

GET /api/schedule/tasks/18/delta?updatedAfterUtcDateTime=2025-01-01T00:00:00Z
  → hasMore: true,  nextAfterId: 50500,
                    nextUpdatedAfterUtcDateTime: "2025-01-10T14:22:00Z"

GET /api/schedule/tasks/18/delta
        ?updatedAfterUtcDateTime=2025-01-10T14:22:00Z&nextAfterId=50500
  → hasMore: false, nextAfterId: null,
                    nextUpdatedAfterUtcDateTime: null
  → Done

Why the delta needs two cursors

updatedUtc has one-second resolution. Bulk scheduling actions — mass publish, schedule import, employee assignment to a class — can produce many records that share the same second.

If a page break lands inside one of those clusters, a single timestamp cursor would force a choice between losing records and re-emitting them. The compound (updatedUtc, id) cursor avoids both:

• The server orders by updatedUtc first, then by id as a tiebreaker.

• "Next page starts after (nextUpdatedAfterUtcDateTime, nextAfterId)" gives a precise restart point even mid-second.

Always pass both nextUpdatedAfterUtcDateTime and nextAfterId together when paging a delta result. Sending just one can either skip records that share the boundary second or return them twice.

Loop pattern

The same loop works for any paged endpoint.

Full pull

GET …/{seasonId}                              # first page, no cursor
loop while hasMore:
    GET …/{seasonId}?nextAfterId={nextAfterId}

Delta pull

GET …/{seasonId}/delta?updatedAfterUtcDateTime={lastSuccessfulSync}

loop while hasMore:
    GET …/{seasonId}/delta
        ?updatedAfterUtcDateTime={nextUpdatedAfterUtcDateTime}
        &nextAfterId={nextAfterId}

When the delta loop finishes, persist the timestamp of the moment your sync started (not the last nextUpdatedAfterUtcDateTime you saw — that's an internal page boundary, not a watermark) and use it as updatedAfterUtcDateTime for the next sync run.

Tombstones

The full pull only returns active records (deleted: false). The delta pull includes deleted records (deleted: true) so that clients can detect deletions and remove them locally.

• On a delta page, treat each record with deleted: true as "this record was removed in flaik" and delete it from your store.

• A record can appear on multiple delta pulls if it has been edited multiple times since the last sync — apply the most recent state. Records are uniquely identified by their endpoint-specific id (e.g. shiftId, taskAssignmentId).

Recovery — what to do when state is lost

If your sync state is lost or corrupted (for example a clean redeploy without persistence), the safest reset is:

1. Clear or quarantine the local store for that season.

2. Run the full pull again to reseed.

3. Record the start time of the full pull and resume delta pulls from there.

You do not need to retain or replay individual nextAfterId cursors across runs — they only have meaning within a single paging loop.

Error responses

HTTP Status	Endpoint	Description
400	Both	The supplied seasonId does not exist for this resort.
400	Delta only	updatedAfterUtcDateTime was not provided.
401	Both	Missing or invalid access token.

See Authentication for token acquisition.

Common pitfalls

• Forgetting nextAfterId on a delta continuation. Sending only updatedAfterUtcDateTime between pages can skip or duplicate records at the boundary second. Always pass both.

• Using nextUpdatedAfterUtcDateTime as your sync watermark. It's a page-boundary value, not a "last sync time". Use the timestamp at which your sync started.

• Looping on the full pull and expecting deletions. The full pull never returns soft-deleted records. Switch to the delta pull as soon as you have an initial seed.

• Assuming pageSize smaller than 1000 reduces server load. It only changes how many records you get per call — total work is the same, more round-trips are usually slower. Use the default unless you have a memory constraint on the client.

Need help? Contact [e-mail].