Sync Protocol
This section will give you a quick overview of the Sync API communication protocol - concepts, the exposed actions, what you can achieve with each one, and a brief overview of how to properly accomplish synchronization.
Treat it as a foundation for the next section where we will dig deeper and learn how to actually make a full synchronization flow.
Concepts
The Sync API allows you to keep your local copy of the data up to date with Sell. It figures out when you last synced, what has changed since then, and what resources you have access to, and it allows you to pull fresh data.
Every time you want to synchronize you must perform the whole synchronization flow, and each time you act within a new synchronization session.
When you start a new synchronization session you must provide a device's universally unique identifier (UUID). Device is a client that wants to keep data in sync. The device's UUID must not change between synchronization sessions, otherwise the sync service will not recognize the device and will send all the data again.
There are three endpoints you will use during synchronization:
- Start endpoint - this is the first endpoint you will hit in order to start a new synchronization session. It returns a synchronization session id you will use to fetch data from the queued data endpoint.
- Queued data endpoint - the endpoint from which you fetch fresh data and related instruction information.
- Acknowledgement endpoint - as you fetch data, you need to acknowledge it. This states that the device has fetched resources and there is no need to send it again.
Sync API Endpoints
The Sync API provides the following endpoints.
| Endpoint | Description |
|---|---|
/v2/sync/start | Start endpoint. |
/v2/sync/:session_id/queues/:queue | Queued data endpoint. |
/v2/sync/ack | Acknowledgement endpoint. |
You can find description of all the endpoints and its parameters in the Sync API reference.
Flow
The Sync API protocol is a stateful protocol over HTTP. The full synchronization flow encompasses at least three main phases:
- Everything begins when you call the Session endpoint first, which sets up a new synchronization process and returns a new synchronization session unique identifier. You must provide a UUID for the device for which you want to perform synchronization. The UUID must not change across synchronizations.
- Using the session identifier, you call continuously the Queued data endpoint to drain queues, until there is no more data to download. At that moment we expose a single queue named
main, for all the known resources. Fetched data include acknowledgement keys you will use later on. - Once you have the data, you should apply instructions to your local copy to keep it in sync.
- As you fetch new data, you need to send acknowledgement keys to the Acknowledgement endpoint. If your connection breaks or anything goes wrong during synchronization, the Sync service will aim to deliver all data next time you try to synchronize. There is a guarantee that the data will eventually arrive, and you can't lose the data. We suggest sending back acks at regular intervals, in manageable packs.
Once you drain all queues, the Sync service will compare all the data you have acknowledged with your data in Sell, to find things that are missing or have changed, and queue new items to synchronize in the next synchronization session.
Synchronization flow
