Repository navigation
Closed
Milestone
Description
Summary
The roadmap, issues, and openapi.yaml use inconsistent naming for CloudKit's change-tracking endpoints, which led to #46 and #47 being closed as "completed" against the wrong operations. This issue documents the canonical Apple surface and what MistKit actually implements, so the spec and roadmap can be reconciled.
Apple's four change-tracking endpoints
Per the CloudKit Web Services Reference:
| Apple endpoint | Purpose | Status |
|---|---|---|
records/changes |
Fetching Record Changes | current |
zones/changes |
Fetching Zone Changes | deprecated — Apple says use changes/database |
changes/database |
Fetching Database Changes — returns which zones changed | current (replacement for zones/changes) |
changes/zone |
Fetching Record Zone Changes — record changes within a zone | current |
What MistKit implements today (openapi.yaml @ docs/sync-beta.2)
- ✅
records/changes→fetchRecordChanges ⚠️ zones/changes→fetchZoneChanges— this is the deprecated endpoint- ❌
changes/database— not in the spec, no wrapper (tracked in Fetching Database Changes (changes/database) #46) - ❌
changes/zone— not in the spec, no wrapper (tracked in Fetching Record Zone Changes (changes/zone) #47)
So no changes/* endpoint is implemented, and the only zone-level coverage we ship is the deprecated zones/changes.
Why this is confusing
- Fetching Database Changes (changes/database) #46 ("Fetching Database Changes (changes/database)") was closed after being mapped to
records/changes— a different endpoint. - Fetching Record Zone Changes (changes/zone) #47 ("Fetching Record Zone Changes (changes/zone)") was closed conflated with
records/changesas well. - The README roadmap lists both under
Backlog / Post-betausing Apple'schanges/*names, while the implemented operations userecords/changes/zones/changesnames — so it's not obvious what's actually shipped.
Proposed resolution
- Spec: add
changes/databaseandchanges/zonetoopenapi.yaml(+ regenerate), and markzones/changes/fetchZoneChangesas deprecated in favor ofchanges/database. - Service: add
CloudKitServicewrappers for the two new endpoints; decide whether to deprecatefetchZoneChanges. - Docs/roadmap: in README, list the four endpoints with both Apple names and MistKit method names, and reflect deprecation.
- Keep Fetching Database Changes (changes/database) #46 / Fetching Record Zone Changes (changes/zone) #47 as the per-endpoint implementation trackers; this issue is the umbrella/clarification.
References
- Fetching Database Changes (changes/database): https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/FetchingDatabaseChanges(changeszone).html
- Fetching Record Zone Changes (changes/zone): https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/FetchingRecordZoneChanges(changeszone).html
- Fetching Zone Changes (zones/changes) — deprecated: https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/GetZoneChanges.html
- Fetching Record Changes (records/changes): https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/ChangeRecords.html
Metadata
Metadata
Assignees
Labels
No labels
Activity
leogdion commentedon Aug 20, 2026
Concerns for #429
1. Wire format is doc-derived, not observed. Local
.claude/docs/webservices.mdis abbreviated on both new endpoints, sochanges/databaseandchanges/zonewere specified from Apple's archived reference pages linked in this issue. No live-service call was made. Both are read-only operations, so the failure mode is a mis-decode rather than data loss — but the schemas should be confirmed against a real response before this ships in a release.2. The deprecation this issue asks for interacts with a possible pre-existing bug — now #430. This issue's resolution #2 asks whether to deprecate
fetchZoneChanges; #429 does deprecate it. Separately, Apple documentszones/changesas usingmetaSyncTokenwhile MistKit sendssyncToken, so that endpoint's pagination may never have worked.openapi.yamlcarries the same contradiction — the description says "meta-sync token" while the property issyncToken.That combination is worth noting explicitly: if #430 confirms the bug, then
zones/changeswas both deprecated by Apple and broken in MistKit, which strengthens the case for the deprecation but also means anyone still on that path should be pushed off it rather than merely warned. #429 does not change the token key — deliberately, since Apple's page contradicts itself and that needs a live response to settle.3. #46 and #47 are closed by #429 as implementations, which is the fix for the mis-mapping this issue documents. Both were previously closed against
records/changes— a different endpoint. They now have real wrappers:fetchDatabaseChanges/fetchAllDatabaseChangesandfetchRecordZoneChanges/fetchAllRecordZoneChanges. Worth confirming that re-closing them against the correct endpoints is the outcome you want, rather than leaving them open pending live verification.The four-endpoint README table with both Apple and MistKit names is in #429, per resolution #3.
🤖 Generated with Claude Code
Add changes/database and changes/zone endpoints; deprecate zones/chan…
Add changes/database and changes/zone endpoints; deprecate zones/chan…
leogdion commentedon Aug 28, 2026
Resolved on
v1.0.0-beta.4via #429 (commit 0b6bea9).changes/databaseandchanges/zoneadded to the spec and service;zones/changesmarked deprecated in favor ofchanges/database.Add changes/database and changes/zone endpoints; deprecate zones/chan…
v1.0.0 beta.4 (#439)