Changes

Changes

Changed on

Every write to the world, in order: each change is an upsert (with the element) or a delete, with its type, id and change_seq. Pass the response's cursor back as since until has_more is false, then poll with it to stay in sync. Any other query parameter is a 422.

get/api/v2/changes

Request

  • Base URL: https://www.onlyworlds.com
  • URL: https://www.onlyworlds.com/api/v2/changes
  • Auth: one of:
    • API key in header API-Key
    • API key in header API-Key and API key in header API-Pin

Query parameters

sincestring

Where to start: the cursor of the previous page, passed back as is, or an integer (changes after that change_seq). Omit it to read from the beginning. Anything else is a 422. (The element lists page with cursor; this feed takes since.)

limitinteger

Page size, 1-1000. Over 1000 is a 422, not clamped.

headboolean

true: only the feed's current position (cursor and head, no changes), to start following from now. since and limit are ignored.

Response

A page of the change feed, oldest change first (by change_seq, then id).

has_moreboolean required
headinteger required

The world's current change_seq. A cursor past it is stale (the world was rewound): pull again from since=0.

epochinteger nullable required

A guest's view epoch (the third part of its cursor), null for everyone else but a contributor's (person or seat), which carries one too. It moves when the reader's view changes with no change_seq move (a Character given or taken, a role, an element hidden from a guest or unhidden): a tip whose epoch differs from the one you last applied means walk again, and the walk answers 409 resync_required. Read it here, never out of the cursor.

epoch_reason'role' | 'view' | 'null' nullable required

Why epoch last moved, beside it (null when epoch is null). role: your own role or membership moved; keep what you hold that a walk from since=0 does not name. view: what you may see moved (a delete, a hide, an unhide, a Character given or taken); drop it. view too for an epoch that never moved. It names the last move only: when your tip is more than one epoch past the one you applied, walk with your cursor, and the 409's reason covers every move since it (role if any was). A tool never empties a copy on its own.

Changes

  • 4dd5b1cd0687Revision changes
    • warning

      added the new character_taken enum value to the / response property for the response status

    • warning

      added the new character_taken enum value to the / response property for the response status

    • warning

      added the new character_taken enum value to the / response property for the response status

    • warning

      added the new character_taken enum value to the / response property for the response status

    • warning

      added the new character_taken enum value to the / response property for the response status

    • warning

      added the new world_full enum value to the / response property for the response status

    • warning

      added the new world_full enum value to the / response property for the response status

    • warning

      added the new world_full enum value to the / response property for the response status

    • warning

      added the new world_full enum value to the / response property for the response status

    • warning

      added the new world_full enum value to the / response property for the response status