Sync Requests

Authentication

All requests to the Sync API must be authenticated and must include a valid access token. You can reuse an existing access token only if it is tagged with sync permission scope.

The sync scope controls whether you can perform a synchronization flow.

To authenticate your device for the Sync API, use the standard Authorization header using the Bearer authentication scheme to transmit the access token. We provide in-depth documentation for the 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 a POST request to the /v2/sync/start Start Session endpoint.

As stated in the previous article you must provide a UUID for the device for which you want to perform synchronization via the X-Basecrm-Device-UUID header.

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/start
Accept: application/json
Authorization: Bearer $ACCESS_TOKEN
X-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.1 204 No Content

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 the queues array will include only a sinqle item - the main queue.

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.1 201 Created
Content-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 a GET request to the provided link in the queue's self link within meta attribute.

GET /v2/sync/$SYNC_SESSION_ID/queues/main
Accept: application/json
Authorization: Bearer $ACCESS_TOKEN
X-Basecrm-Device-UUID: $CLIENT_DEVICE_UUID

You must keep hitting it, until there is no more data to download and the Sync service returns the 204 No Content status code.

HTTP/1.1 204 No Content

If you get 200, then payload will include data and instructions how to proceed.

The items array includes resources in the same format as if they were requested via the REST API. Additional Sync related attributes are provided within meta/sync object and include:

• event_type - an event type,
• ack_key - an acknowledgement key,
• revision - data revision identifier.

HTTP/1.1 200 OK
Content-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 the Acknowledgement endpoint.

Each synced item has an associated ack_key attribute sent within the meta object. Simply send a POST request to the /v2/sync/ack endpoint and provide ack_keys within JSON formatted payload.

POST /v2/sync/ack
Authorization: Bearer $ACCESS_TOKEN
Content-Type: application/json
X-Basecrm-Device-UUID: $CLIENT_DEVICE_UUID
{
  "data": {
    "ack_keys": [
      "Contact-976368-1375200190",
      "..."
    ]
  }
}

As a response you should get the 202 status code.

HTTP/1.1 202 Accepted

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.