CIX Developer Documentation

Sync


Introduction

Sync and Commit are the mechanisms by which the API allows clients to retrieve a list of all messages added or changed since a previous sync time, and to allow the sync to safely continue to send the same lists until the client signals that it has correctly retrieved all the messages on its side. In general, Sync and Commit are suggested for desktop off-line clients rather than web-based clients for which the topic and conversation APIs are more suited.

Sync and Commit keep track of the last message sent based on an unique delta ID. The format of the delta ID is entirely up to the client itself and is simply an string that should both unique and consistent for the same client on each platform. Thus it is suggested that a UUID is used for this. As an example, if you were writing a client called CIXReader to run on Windows, MacOS and iOS then each client should have its own delta ID for each CIX user on that platform.

When starting from an empty client state with no local messages, the first call to Sync with a new delta ID will retrieve the last 7 days worth of messages. Once these messages have been successfully received from the API, the client should issue a Commit call with the same delta ID. This will mark that a subsequent call to Sync will then retrieve all messages added or changed since the end of the last Sync. Calling Sync in succession without a call to Commit in between will, however, return the same set of messages returned by the last Sync plus any new messages added or changed in the interim.