protocol
Any client can sync with a Termix server through the sync endpoints. The desktop app uses them, and the same endpoints are open to other clients. The reference for each endpoint is in the API reference under Sync.
The flow
GET /sync/v2/infois public. It says the server is Termix and gives itsprotocolnumber. Stop if you don't support that number.- Sign in with any normal login method to get a short session.
POST /sync/v2/linktrades that session for a long lived device session. Send adeviceName, aclientTypeand adeviceId. The login session is ended.- Pull with
GET /sync/v2/changes, push withPOST /sync/v2/push, and listen onGET /sync/v2/eventsto know when to pull. POST /sync/v2/session/refreshrenews the device session when it ends within 60 days.POST /sync/v2/unlinkends it.
Send the device session as the jwt cookie.
Client type and device id
| Field | Values | Default |
|---|---|---|
| clientType | desktop, mobile, web, cli, master | desktop |
| deviceId | 8 to 100 letters, digits, dots, dashes, underscores | none |
Both are optional, so older clients keep working. A client with a deviceId shows up in GET /sync/v2/devices, which lists the clients linked to the account. Keep the deviceId the same for an install.
Revisions and the cursor
Every synced record has a revision and a position in the change feed called seq.
- Pull with a
cursor. Start at 0. Each page returnsnextCursorandhasMore. SavenextCursorand use it next time. - Push ops with the
baseRevisionyou last saw. If the server moved on, the answer is a conflict with the server's version. The server's version wins and you decide what to do with yours. - To start pulling a kind of data you never pulled, pull it from cursor 0 with
types, then continue from the feed cursor. - Process changes in
orderof the entity types the page lists, so records that point at others arrive after their targets.
Rows
Secrets travel inside the rows in plain text and are encrypted again at rest on each side, so only sync over HTTPS. Records that point at other records use the other record's syncId, never a local id.