Sync Requests
Authentication
All requests to the Sync APImustbe authenticated andmustinclude a validaccess token. You can reuse an existing access token only if it is tagged withsyncpermission scope.
Thesyncscope controls whether you can perform a synchronization flow.
To authenticate your device for the Sync API, use the standardAuthorization头t使用不记名的身份认证方案ransmit the access token. We provide in-depth documentation forthe OAuth 2.0 protocol.
Scope
| Name | Description |
|---|---|
sync |
Grant read-only access to all your data via the Sync API. |
Authorization: Bearer $ACCESS_TOKEN
Start Synchronization Flow
To start a new synchronization flow you send aPOSTrequest to the/v2/sync/startStart Sessionendpoint.
As stated inthe previous articleyou must provide a UUID for the device for which you want to perform synchronization via theX-Basecrm-Device-UUIDheader.
A device UUID is a string that you generate and then reuse across synchronization sessions. The UUID must not change. The Sync service uses this to track everything you acknowledge.
If you change the UUID, sync will assume you have nothing and will send you all data.
POST/v2/sync/startAccept:application/jsonAuthorization:Bearer$ACCESS_TOKENX-Basecrm-Device-UUID:$CLIENT_DEVICE_UUID
If you get a 204 response, there is nothing to download, and you can stop the flow.
HTTP/1.1204NoContent
If you get a 201 response, there is data to synchronize.
The payload includes a session unique identifier you use to fetch data from queues later on, and an array of queues to synchronize. At this moment thequeuesarray will include only a sinqle item - themainqueue.
The queue object includes number of pages left and the number of elements to sychronize.
The numbers aim to be close as possible to actual state, but they can act as a guide to how much data you can expect. The reason for this is that our Sync service is optimized for getting data to the device as fast as possible, and if some records are deleted, created etc. during the synchronization, it might have more instructions in the queues.
HTTP/1.1201CreatedContent-Type:application/json{"data":{"id":"$SYNC_SESSION_ID","queues":[{"data":{"name":"main","pages":10,"total_count":2000},"meta":{"type":"sync_queue","links":{"self":“https://api.getbase.com/v2/sync/ SYNC_SESSION_ID /美元queues/main"}}}]},"meta":{"type":"sync_session"}}
Fetch Queued Data
Once you have a session identifier and a link to the main queue you can fetch data from the queue.
To start draining the queue, perform aGETrequest to the provided link in the queue's self link withinmetaattribute.
GET/v2/sync/$SYNC_SESSION_ID/queues/mainAccept:application/jsonAuthorization:Bearer$ACCESS_TOKENX-Basecrm-Device-UUID:$CLIENT_DEVICE_UUID
You must keep hitting it, until there is no more data to downloadand the Sync service returns the 204 No Content status code.
HTTP/1.1204NoContent
If you get 200, then payload will include data and instructions how to proceed.
Theitemsarray includes resources in the same format as if they were requested via the REST API. Additional Sync related attributes are provided withinmeta/syncobject and include:
event_type- an event type,ack_key- an acknowledgement key,revision- data revision identifier.
HTTP/1.1200OKContent-Type:application/json{"items":[{"data":{"id":1,"creator_id":1,"name":"Our website","updated_at":"2014-08-27T17:32:56Z","created_at":"2014-08-27T16:32:56Z"},"meta":{"type":"source","sync":{"event_type":"updated","ack_key":"Source-976368-1375200190","revision":1375200207}}},{"data":{"id":1},"meta":{"type":"note","sync":{"event_type":"deleted","ack_key":"Note-976369-0","revision":0}}}],"meta":{"type":"collection","count":2,"count_left":0}}
The queue holds only the freshest data, there are no historical data stored.
Deleted resources will include only ids, and you should treat it as an instruction to perform a local delete.
Acknowledge Received Data
Whenever you add fetched data to your local data store, in order for the Sync service to know which data you have, you need to send acknowledgement keys to theAcknowledgementendpoint.
Each synced item has an associatedack_keyattribute sent within themetaobject. Simply send aPOSTrequest to the/v2/sync/ackendpoint and provideack_keyswithin JSON formatted payload.
POST /v2/sync/ackAuthorization:Bearer $ACCESS_TOKENContent-Type:application/jsonX-Basecrm-Device-UUID:$CLIENT_DEVICE_UUID{"data":{"ack_keys":["Contact-976368-1375200190","..."]}}
As a response you should get the 202 status code.
HTTP/1.1202Accepted
Group acknowledgement keys together and send them back at regular intervals. If your connections break, this will allow the next synchronization session to pick up where you left off or close to that point.