Sync API
This document outlines the client-server communication of the Standard Notes ecosystem.
#
ItemAn Item
is largely the only model that both clients and server are concerned wtih. The content
field stores an encrypted object that can be anything the client needs to operate.
Relationships between items are handled by the client, and not the server, and are stored encrypted in the content
field as references
.
Items have the following properties:
name | type | description |
---|---|---|
uuid | string (or uuid for some databases) | The unique identifier for this item. |
content | text | An encrypted string generated by the client. |
content_type | string | The type of data contained in the content field. (i.e Note, Tag, SN |
enc_item_key | text | The key used to encrypt content , itself also encrypted. |
deleted | boolean | Whether the model has been deleted. |
created_at_timestamp | integer | Timestamp representing when the item was created, with microsecond precision. |
updated_at_timestamp | integer | Timestamp representing when the item was updated by the server, with microsecond precision. |
#
ContentData generated by the client is stored in the content
field of the Item
. An item's content
is "sticky" and can have any property the client chooses, as well as the following:
name | type | description |
---|---|---|
appData | dictionary | A domain based dictionary whose content must be preserved between platforms. appData[domain] contains data the client stores in the item. |
references | array | A metadata array of other Item uuids this item is related to and their respective content_type . See sample below. |
references
array structure:
#
REST APIGeneral:
All requests after initial authentication should be authenticated with a session token in the
Authorization
header:
#
POST items/syncapi | string | The API version to use. Must not be null, otherwise oldest API version used. Latest value is "20200115". |
compute_integrity | boolean | Should be false in most cases. Pass true if you plan to read the integrity_hash result (integrity can be optionally checked once on app launch). |
items | array | An array of Items. |
limit | integer | The maximum number of items to return per request. Official clients use 150. |
sync_token | string | An opaque token returned by the server from a previous sync request. This lets the server know to pull in only new changes. |
cursor_token | string | An opaque pagination token returned by the server from a previous multi-page sync request. Send this value back only if the server returned this value from a previous request. |
#
Responseretrieved_items | Items that are new to the client or have been modified since last sync and should be merged with local values or created locally. |
saved_items | Items which have been successfully saved. Clients should merge only the resulting updated_at_timestamp with local values. Do not update local value of content from remote saved_items value. |
conflicts | Items which have not been saved by the server and returned to client. |
sync_token | An opaque token which should be sent back to server in subsequent sync request. |
cursor_token | An opaque token which should be sent back to server in subsequent sync request (if present). |
#
ConflictsA sync_conflict
occurs when the item the client is attempting to save has a newer change on the server. The server is able to determine this by reading the updated_at_timestamp
value from both the incoming payload and the server payload. If the incoming payload's updated_at_timestamp
!= to the server's updated_at_timestamp
for that item, the save is rejected and returned to client as a sync_conflict
. These types of conflicts are not uncommon.
To resolve a sync_conflict
, the client must choose a winner between server_item and unsaved_item then re-sync. The winning item should have its updated_at_timestamp value set to the server's value.
A uuid_conflict
occurs when the UUID the client has choosen for an item for X user already belongs to an item for Y user. This should mostly only occur when a user registers a new account and imports a data backup from another account.
To resolve a uuid_conflict
, change the UUID of the item attempting to be saved to a new UUID, then re-sync.
#
DeletionTo delete an item permanently, set deleted
to true
on the Item
and sync. When receiving an item that is deleted
, remove it from the local database immediately.