This document outlines the client-server communication of the Standard Notes ecosystem.
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
Items have the following properties:
|uuid||The unique identifier for this item.|
|content||An encrypted string generated by the client.|
|content_type||The type of data contained in the |
|enc_item_key||The key used to encrypt |
|deleted||Whether the model has been deleted.|
|created_at_timestamp||Timestamp representing when the item was created, with microsecond precision.|
|updated_at_timestamp||Timestamp representing when the item was updated by the server, with microsecond precision.|
Data 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:
|appData||A domain based dictionary whose content must be preserved between platforms. |
|references||A metadata array of other |
references array structure:
All requests after initial authentication should be authenticated with a session token in the
Authorizationheader:Authorization: Bearer <access token>
|api||The API version to use. Must not be null, otherwise oldest API version used. Latest value is "20200115".|
|compute_integrity||Should be false in most cases. Pass true if you plan to read the |
|items||An array of Items.|
|limit||The maximum number of items to return per request. Official clients use 150.|
|sync_token||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||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.|
|retrieved_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 |
|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).|
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.
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.
To delete an item permanently, set
true on the
Item and sync. When receiving an item that is
deleted, remove it from the local database immediately.