Seq

Read the objects that changed since a position in the shop's sequence: each one whole, as it is now, and the position to read from next.

Request

• {seq} is a position in the sequence: 0 to start from the beginning, and after that, the "seq" that your last call returned. It is a decimal integer without leading zeros.

The request has no body. The key needs the seq permission.

Headers

Response

We answer 200 OK with a JSON object, without white space:

{
    "changes": [
        {
            "type": "transaction",
            "id": 378,
            "rev": 3,
            …
        },
        {
            "type": "subscriber",
            "id": 19,
            "rev": 2,
            …
        },
        {
            "type": "charge",
            "id": 379,
            "rev": 1,
            …
        }
    ],
    "seq": 164
}

Each change is the object as it is when you call, whole, not the difference from before. An object that changed several times since {seq} is usually returned once, but can be returned more than once, even in one response: apply each copy only if its "rev" is higher than the one you have, and the result is the same. A client must skip a "type" it doesn't know.

Size

A response holds as many changes as fit in 64 KiB, and at least one, however large. Call again from the "seq" it returned until a call returns no changes. The limit may change, so read the response whole, whatever its length.

Order

The sequence keeps the order that merging needs:

1. A transaction first appears after every transaction with a lower "id", and a subscriber after every subscriber with a lower one, so there are no gaps.
2. A charge first appears after its subscriber, at the subscriber's "rev" that the charge names, or a later one.

These hold for the sequence read from 0. See What seq guarantees.

Errors

Besides the errors that any request can give, which Errors lists:

Seq doesn't check that {seq} is a position it returned. One beyond the end of the sequence returns no changes and the same "seq", as if you were up to date, until the shop has had that many changes. So store only a "seq" that seq returned, and never add to it yourself.

Seq is safe to retry, and to call as often as you like: it changes nothing. A call that returns no changes costs us little, so a timer that calls it every minute or so, as a safety net beside pings, is fine.