Skip to content

Clarify change-tracking endpoint coverage (changes/* vs records/changes + deprecated zones/changes) #401

Closed

Description

@leogdion

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)

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/changes as well.
  • The README roadmap lists both under Backlog / Post-beta using Apple's changes/* names, while the implemented operations use records/changes / zones/changes names — so it's not obvious what's actually shipped.

Proposed resolution

  1. Spec: add changes/database and changes/zone to openapi.yaml (+ regenerate), and mark zones/changes / fetchZoneChanges as deprecated in favor of changes/database.
  2. Service: add CloudKitService wrappers for the two new endpoints; decide whether to deprecate fetchZoneChanges.
  3. Docs/roadmap: in README, list the four endpoints with both Apple names and MistKit method names, and reflect deprecation.
  4. 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

Related: #46, #47

Activity

  1. added this to the v1.0.0-beta.4 milestone on Aug 20, 2026
  2. leogdion commented on Aug 20, 2026

    @leogdion
    MemberAuthor

    Concerns for #429

    1. Wire format is doc-derived, not observed. Local .claude/docs/webservices.md is abbreviated on both new endpoints, so changes/database and changes/zone were 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 documents zones/changes as using metaSyncToken while MistKit sends syncToken, so that endpoint's pagination may never have worked. openapi.yaml carries the same contradiction — the description says "meta-sync token" while the property is syncToken.

    That combination is worth noting explicitly: if #430 confirms the bug, then zones/changes was 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/fetchAllDatabaseChanges and fetchRecordZoneChanges/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

  3. leogdion commented on Aug 28, 2026

    @leogdion
    MemberAuthor

    Resolved on v1.0.0-beta.4 via #429 (commit 0b6bea9). changes/database and changes/zone added to the spec and service; zones/changes marked deprecated in favor of changes/database.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions