Change Discovery

The Change Discovery API lets a repository publish a stream of what changed — created, updated, and deleted resources — as a W3C Activity Streams OrderedCollection. iiisight consumes that stream so a harvester can find changed resources and re-fetch them.

Activities are ordered oldest → newest across the (usually paged) collection. iiisight walks the pages for you.

Iterating activities

iter_activities yields Activity objects across all pages. By default it walks newest-first (from last backwards) — the common “what changed recently” case:

async with iiisight.AsyncClient() as client:
    async for activity in client.iter_activities("https://example.org/activity/all-changes"):
        print(activity.end_time, activity.type, activity.object.id)
        if activity.type != "Delete":
            doc = await client.resolve(activity.reference)   # re-fetch the changed resource

with iiisight.Client() as client:
    for activity in client.iter_activities("https://example.org/activity/all-changes"):
        print(activity.end_time, activity.type, activity.object.id)
        if activity.type != "Delete":
            doc = client.resolve(activity.reference)

Each Activity has a type (Create / Update / Delete / Move / Add / Remove / Refresh), an object (a Reference to the changed resource), an end_time, and an optional actor. Its .reference plugs straight into client.resolve(...).

Incremental harvesting with since

Pass since (an endTime string) to process only newer activities — and, walking newest-first, iteration stops as soon as it reaches activities at or before since, so you never page further back than you need:

async for activity in client.iter_activities(url, since="2024-01-01T00:00:00Z"):
    ...

For a full oldest-first sync, pass newest_first=False (walks from first forwards via next).

Note

since is compared against endTime as a string, so timestamps should be ISO 8601 in a consistent form (UTC Z), which is what Change Discovery uses.

Fetching the collection directly

collection = await client.fetch_changes(url)   # a ChangeCollection
collection.total_items
collection.first, collection.last               # page URLs

From the command line

$ iiisight changes https://example.org/activity/all-changes --limit 20
2024-03-01T09:00:00Z      Update    https://example.org/iiif/book1/manifest
2024-02-28T12:30:00Z      Create    https://example.org/iiif/book2/manifest
...

--since <endTime> limits to newer activities; --limit N stops after N.