ObexCode Logo ObexCode Logo

Developer Zone

Table of Contents

Sync Engine API

The Sync Engine API is used to set up Sync Bindings. The Sync Engine is the part that does the synchronization between two Sync Clients. It will receive a set of changes from each client, compare the changes, and send the computed changes back to the clients.

Concepts

Sync Clients

A Sync Client represents a specific device or user registered with a sync source. For SyncML this will be a specific phone registered. For Datastore it will be an end user account.

A Sync Client provides an internal API for exchanging sets of changes between two registered Sync Clients. When registering a Synch Binding, you first need to create two Sync Clients, before registering the actual binding. Note that each Sync Client will have it's own specific API.

Examples of Sync Clients are SyncML, Datastore and Gdata. Support for other client may be added in the future.

Sync Engine

The engine is responsible for performing the actual synchronization computation. It has two basic modes of operation: client initiated sync and server initiated sync.

The engine has a single-function synchronization, which means it needs to get all changes from both parties in the synchonization at the moment of the sync. It will then iterate over the data, and pass the computed changes back to the sync sources. For full (slow) sync the engine will also check the data for duplicates.

Sync Binding

A Sync Binding is a registered connection between two specific Sync Clients. It identifies the Sync Clients used by uuid of the clients. When synchronizing this is used to look up the peer of a client initiating the sync, or to look up the parties in a server initiated sync.

Client initiated sync

Due to the nature of the SyncML protocol, the SyncML sync source needs to gather the changes from the sync client (phone) before doing the actual synchronization with the engine. After gathering the data, the sync source calls the engine, providing the gathered data. The engine then queries the other sync source in the binding for changes, computes the final change sets, pushes the changes to the target, and returns the changes for the SyncML sync source.

<insert figure>

Server initiated sync

If both Sync Clients in a specific binding supports server initiated sync, the sync engine itself can be queried to initiate the sync. The engine will then request the changes from both sources, compare them and push changes back to both sources.

<insert figure>

Dataclasses

We specify a set of dataclasses that may be supported by the different Sync Clients. These classes are currently "Contacts", "Events", "Tasks" and "Notes". In addition the dataclass "Calendar" is used to specify that both "Tasks" and "Events" are grouped together.

REST Endpoints

These REST endpoints are available in the SyncEngine API

API Endpoint Supported Operations
Bindings http://api.obexcode.com/v2/syncengine/ GET, POST, PUT, DELETE
Sources http://api.obexcode.com/v2/syncengine/sources/ GET, POST
Synchronization http://api.obexcode.com/v2/syncengine/synchronization/ GET, POST

Authentication

Access to the SyncEngine API requires authentication. Even with authentication, only the bindings for the authenticated user is available.

Binding API

Being the API for creating bindings.

Rest endpoint

API Endpoint Supported Operations
Bindings http://api.obexcode.com/v2/syncengine/ GET, POST, DELETE

List all bindings

Request:

GET /v2/syncengine/ HTTP/1.1
Host: api.obexcode.com
Content-Type: application/atom+xml
Accept: application/atom+xml

Response:

HTTP/1.1 200 OK
Content-Type: application/atom+xml
Content-Length: 2030

<feed xmlns="http://www.w3.org/2005/Atom">
  <author>
    <name>ObexCode AS</name>
  </author>
  <id>http://api.obexcode.com/v2/syncengine/</id>
  <link href="http://api.obexcode.com/v2/syncengine/" rel="self" />
  <title>Sync Engine Bindings</title>
  <entry>
    <author>
      <name>admin</name>
      <email>support@obexcode.com</email>
    </author>
    <id>http://api.obexcode.com/v2/syncengine/3</id>
    <link href="http://api.obexcode.com/v2/syncengine/3" rel="self" />
    <link href="http://api.obexcode.com/v2/syncengine/3/edit" rel="edit" />
    <link href="http://api.obexcode.com/v2/syncengine/3" rel="alternate" type="text/html" />
    <source xmlns="http://schemas.obexcode.com/syncserver/2009">
      <sync_source>syncml</sync_source>
      <uuid>2fb295cc-0e50-11de-81c8-002215064801</uuid>
    </source>
    <title>3</title>
    <conflict_winner xmlns="http://schemas.obexcode.com/syncserver/2009">source</conflict_winner>
    <target xmlns="http://schemas.obexcode.com/syncserver/2009">
      <sync_source>google</sync_source>
      <uuid>51579fd6-01a5-11de-8505-002215064801</uuid>
    </target>
  </entry>
  <entry>
    <author>
      <name>admin</name>
      <email>support@obexcode.com</email>
    </author>
    <id>http://api.obexcode.com/v2/syncengine/5</id>
    <link href="http://api.obexcode.com/v2/syncengine/5" rel="self" />
    <link href="http://api.obexcode.com/v2/syncengine/5/edit" rel="edit" />
    <link href="http://api.obexcode.com/v2/syncengine/5" rel="alternate" type="text/html" />
    <source xmlns="http://schemas.obexcode.com/syncserver/2009">
      <sync_source>syncml</sync_source>
      <uuid>2e3b9838-29bc-11de-a8bb-002215064801</uuid>
    </source>
    <title>5</title>
    <conflict_winner xmlns="http://schemas.obexcode.com/syncserver/2009">source</conflict_winner>
    <target xmlns="http://schemas.obexcode.com/syncserver/2009">
      <sync_source>datastore</sync_source>
      <uuid>2e3be5a4-29bc-11de-a8bb-002215064801</uuid>
    </target>
  </entry>
</feed>

Specific binding

Request:

GET /v2/syncengine/4/ HTTP/1.1
Host: api.obexcode.com
Content-Type: application/atom+xml
Accept: application/atom+xml

Response:

HTTP/1.1 200 OK
Content-Type: application/atom+xml
Content-Length: 913

<entry xmlns="http://www.w3.org/2005/Atom">
  <author>
    <name>admin</name>
    <email>support@obexcode.com</email>
  </author>
  <id>http://api.obexcode.com/v2/syncengine/4</id>
  <link href="http://api.obexcode.com/v2/syncengine/4" rel="self" />
  <link href="http://api.obexcode.com/v2/syncengine/4/edit" rel="edit" />
  <link href="http://api.obexcode.com/v2/syncengine/4" rel="alternate" type="text/html" />
  <source xmlns="http://schemas.obexcode.com/syncserver/2009">
    <sync_source>syncml</sync_source>
    <uuid>3fe85584-12d9-11de-b2ce-002215064801</uuid>
  </source>
  <title>4</title>
  <conflict_winner xmlns="http://schemas.obexcode.com/syncserver/2009">source</conflict_winner>
  <target xmlns="http://schemas.obexcode.com/syncserver/2009">
    <sync_source>google</sync_source>
    <uuid>51579fd6-01a5-11de-8505-002215064801</uuid>
  </target>
</entry>

Create binding

To create a binding, POST an entry to the REST Endpoint containing the source, target and conflict_winner specification. Conflict winner must be one of "source" or "target", but may be omitted, in which case "source" is assumed.

The new entry will be returned if successful.

Possible responses

201 Created
Binding created successfully. Response will contain the updated binding entry.
400 Binding entry not provided
Post was done without an entry.
400 Binding source not provided
Posted binding entry does not contain the required binding source.
400 Binding target not provided
Posted binding entry does not contain the required binding target.

Example

Request:

POST /v2/syncengine/ HTTP/1.1
Host: api.obexcode.com
Content-Type: application/atom+xml
Content-Length: 486
Accept: application/atom+xml

<entry xmlns="http://www.w3.org/2005/Atom">
  <source xmlns="http://schemas.obexcode.com/syncserver/2009">
    <sync_source>syncml</sync_source>
    <uuid>d0d68c44-29ba-11de-ae4e-002215064801</uuid>
  </source>
  <target xmlns="http://schemas.obexcode.com/syncserver/2009">
    <sync_source>datastore</sync_source>
    <uuid>bfb85fc8-30a9-11de-b930-002215064801</uuid>
  </target>
  <conflict_winner xmlns="http://schemas.obexcode.com/syncserver/2009">source</conflict_winner>
</entry>

Response:

HTTP/1.1 200 OK
Content-Type: application/atom+xml
Content-Length: 920

<entry xmlns="http://www.w3.org/2005/Atom">
  <author>
    <name>admin</name>
    <email>support@obexcode.com</email>
  </author>
  <id>http://api.obexcode.com/v2/syncengine/12</id>
  <link href="http://api.obexcode.com/v2/syncengine/12" rel="self" />
  <link href="http://api.obexcode.com/v2/syncengine/12/edit" rel="edit" />
  <link href="http://api.obexcode.com/v2/syncengine/12" rel="alternate" type="text/html" />
  <source xmlns="http://schemas.obexcode.com/syncserver/2009">
    <sync_source>syncml</sync_source>
    <uuid>d0d68c44-29ba-11de-ae4e-002215064801</uuid>
  </source>
  <title>12</title>
  <conflict_winner xmlns="http://schemas.obexcode.com/syncserver/2009">source</conflict_winner>
  <target xmlns="http://schemas.obexcode.com/syncserver/2009">
    <sync_source>datastore</sync_source>
    <uuid>bfb85fc8-30a9-11de-b930-002215064801</uuid>
  </target>
</entry>

Update binding

Editing of an existing binding is limited to only allow editing of the conflict_winner field. Editing the source or target sync sources is not desirable since changes to these values implies a new binding. The method returns the updated object.

Possible responses

200 Updated
Binding updated successfully. Response will contain the updated binding entry.
400 No binding ID provided
The update request must be performed on a specific ID.
400 No Entry provided
Must have some data to update with.
403 Forbidden
Attempt at updating a binding that does not belong to the authenticated user.
404 Unknown Sync Binding
The provided ID does not exist.

Example

Request:

PUT /v2/syncengine/12/ HTTP/1.1
Host: api.obexcode.com
Content-Type: application/atom+xml
Content-Length: 486
Accept: application/atom+xml

<entry xmlns="http://www.w3.org/2005/Atom">
  <conflict_winner xmlns="http://schemas.obexcode.com/syncserver/2009">target</conflict_winner>
</entry>

Response:

HTTP/1.1 200 Updated
Content-Type: application/atom+xml
Content-Length: 920

<entry xmlns="http://www.w3.org/2005/Atom">
  <author>
    <name>admin</name>
    <email>support@obexcode.com</email>
  </author>
  <id>http://api.obexcode.com/v2/syncengine/12</id>
  <link href="http://api.obexcode.com/v2/syncengine/12" rel="self" />
  <link href="http://api.obexcode.com/v2/syncengine/12/edit" rel="edit" />
  <link href="http://api.obexcode.com/v2/syncengine/12" rel="alternate" type="text/html" />
  <source xmlns="http://schemas.obexcode.com/syncserver/2009">
    <sync_source>syncml</sync_source>
    <uuid>d0d68c44-29ba-11de-ae4e-002215064801</uuid>
  </source>
  <title>12</title>
  <conflict_winner xmlns="http://schemas.obexcode.com/syncserver/2009">target</conflict_winner>
  <target xmlns="http://schemas.obexcode.com/syncserver/2009">
    <sync_source>datastore</sync_source>
    <uuid>bfb85fc8-30a9-11de-b930-002215064801</uuid>
  </target>
</entry>

Delete binding

Deleting is done using an HTTP DELETE call to the specific binding URL.

Possible responses

200 Deleted
Binding is properly deleted.
403 Forbidden
Attempt at deleting a binding that does not belong to the authenticated user.
404 Unknown Sync Binding
The provided ID does not exist.

Example

Request:

DELETE /v2/syncengine/12/ HTTP/1.1
Host: api.obexcode.com
Content-Type: application/atom+xml
Content-Length: 0
Accept: application/atom+xml

Response:

HTTP/1.1 200 Deleted

FIXME: bug in markdown.

Sync Source API

Not implemented yet

The Sync Source API can be used to list the existing sync sources in the system, as well as registering new sources.

List sources

TBD

Register a new source

This can be used to register a new source endpoint. Currently we only support endpoints implementing the google data interface for contacts and calendar.

Synchronization API

Not implemented yet

The synchronization API is primarily used for starting synchronization from the sync engine. In addition it is possible to list statistics of earlier synchronizations. The logged data is only statistical, and does not show what data has been transfered through the sync engine. (Unlike the SyncML chat log)

REST Endpoints

API Endpoint Supported Operations
Synchronization http://api.obexcode.com/v2/syncengine/synchronization/ GET, POST

List all synchronizations

Request:

GET /v2/syncengine/synchronization/ HTTP/1.1
Host: api.obexcode.com
Content-Type: application/atom+xml
Accept: application/atom+xml

Response:

HTTP/1.1 200 OK
Content-Type: application/atom+xml
Content-Length: 2030

<feed xmlns="http://www.w3.org/2005/Atom">
  <id>http://api.obexcode.com/v2/syncengine/synclog</id>
  <link href="http://api.obexcode.com/v2/syncengine/synclog/all.xml/all.xml" rel="self" />
  <link href="http://api.obexcode.com/v2/syncengine/synclog/all.xml" rel="alternate" type="text/html" />
  <title>SyncEngine Log</title>
  <entry>
    <content src="http://api.obexcode.com/v2/syncengine/synclog/2" type="html" />
    <id>http://api.obexcode.com/v2/syncengine/synclog/2</id>
    <link href="http://api.obexcode.com/v2/syncengine/synclog/2" rel="self" />
    <link href="http://api.obexcode.com/v2/syncengine/synclog/2" rel="alternate" type="text/html" />
    <published>2009-03-18T10:00:47Z</published>
    <title>syncml - google</title>
    <sync_stats xmlns="http://schemas.obexcode.com/syncserver/2009">
      <duplicates_detected>0</duplicates_detected>
      <duplicates_removed>0</duplicates_removed>
      <conflicts_detected>0</conflicts_detected>
      <source>
        <sync_source type="syncml" />
        <statistics>
          <adds_in>5</adds_in>
          <replaces_in>0</replaces_in>
          <deletes_in>0</deletes_in>
          <adds_out>4</adds_out>
          <replaces_out>0</replaces_out>
          <deletes_out>0</deletes_out>
        </statistics>
      </source>
      <target>
        <sync_source type="google" />
        <statistics>
          <adds_in>4</adds_in>
          <replaces_in>0</replaces_in>
          <deletes_in>0</deletes_in>
          <adds_out>5</adds_out>
          <replaces_out>0</replaces_out>
          <deletes_out>0</deletes_out>
        </statistics>
      </target>
    </sync_stats>
    <sync_mode xmlns="http://schemas.obexcode.com/syncserver/2009">201</sync_mode>
    <dataclass>Contacts</dataclass>
  </entry>
  <entry>
    <content src="http://api.obexcode.com/v2/syncengine/synclog/1" type="html" />
    <id>http://api.obexcode.com/v2/syncengine/synclog/1</id>
    <link href="http://api.obexcode.com/v2/syncengine/synclog/1" rel="self" />
    <link href="http://api.obexcode.com/v2/syncengine/synclog/1" rel="alternate" type="text/html" />
    <published>2009-03-18T09:58:17Z</published>
    <title>syncml - google</title>
    <sync_stats xmlns="http://schemas.obexcode.com/syncserver/2009">
      <duplicates_detected>0</duplicates_detected>
      <duplicates_removed>0</duplicates_removed>
      <conflicts_detected>0</conflicts_detected>
      <source>
        <sync_source type="syncml" />
        <statistics>
          <adds_in>5</adds_in>
          <replaces_in>0</replaces_in>
          <deletes_in>0</deletes_in>
          <adds_out>4</adds_out>
          <replaces_out>0</replaces_out>
          <deletes_out>0</deletes_out>
        </statistics>
      </source>
      <target>
        <sync_source type="google" />
        <statistics>
          <adds_in>4</adds_in>
          <replaces_in>0</replaces_in>
          <deletes_in>0</deletes_in>
          <adds_out>5</adds_out>
          <replaces_out>0</replaces_out>
          <deletes_out>0</deletes_out>
        </statistics>
      </target>
    </sync_stats>
    <sync_mode xmlns="http://schemas.obexcode.com/syncserver/2009">201</sync_mode>
    <dataclass>Contacts</dataclass>
  </entry>
</feed>

List all synchronizations for a specific binding

Request:

GET /v2/syncengine/15/synchronization/ HTTP/1.1
Host: api.obexcode.com
Content-Type: application/atom+xml
Accept: application/atom+xml

Response:

HTTP/1.1 200 OK
Content-Type: application/atom+xml
Content-Length: 2030

<feed xmlns="http://www.w3.org/2005/Atom">
  <id>http://api.obexcode.com/v2/syncengine/synclog</id>
  <link href="http://api.obexcode.com/v2/syncengine/4/synclog/all.xml/all.xml" rel="self" />
  <link href="http://api.obexcode.com/v2/syncengine/4/synclog/all.xml" rel="alternate" type="text/html" />
  <title>SyncEngine Log</title>
  <entry>
    <content src="http://api.obexcode.com/v2/syncengine/synclog/3" type="html" />
    <id>http://api.obexcode.com/v2/syncengine/synclog/3</id>
    <link href="http://api.obexcode.com/v2/syncengine/synclog/3" rel="self" />
    <link href="http://api.obexcode.com/v2/syncengine/synclog/3" rel="alternate" type="text/html" />
    <published>2009-03-19T09:52:28Z</published>
    <title>syncml - google</title>
    <sync_stats xmlns="http://schemas.obexcode.com/syncserver/2009">
      <duplicates_detected>0</duplicates_detected>
      <duplicates_removed>0</duplicates_removed>
      <conflicts_detected>0</conflicts_detected>
      <source>
        <sync_source type="syncml" />
        <statistics>
          <adds_in>5</adds_in>
          <replaces_in>0</replaces_in>
          <deletes_in>0</deletes_in>
          <adds_out>4</adds_out>
          <replaces_out>0</replaces_out>
          <deletes_out>0</deletes_out>
        </statistics>
      </source>
      <target>
        <sync_source type="google" />
        <statistics>
          <adds_in>4</adds_in>
          <replaces_in>0</replaces_in>
          <deletes_in>0</deletes_in>
          <adds_out>5</adds_out>
          <replaces_out>0</replaces_out>
          <deletes_out>0</deletes_out>
        </statistics>
      </target>
    </sync_stats>
    <sync_mode xmlns="http://schemas.obexcode.com/syncserver/2009">201</sync_mode>
    <dataclass>Contacts</dataclass>
  </entry>
</feed>

Start synchronization

Request:

POST /v2/syncengine/15/synchronization/ HTTP/1.1
Host: api.obexcode.com
Content-Type: application/atom+xml
Content-Length: 486
Accept: application/atom+xml

<entry xmlns="http://www.w3.org/2005/Atom">
  <sync_mode>201</sync_mode>
  <dataclass>Contacts</dataclass>
</entry>

Response:

HTTP/1.1 200 OK
Content-Type: application/atom+xml
Content-Length: 920

<entry>
  <content src="http://api.obexcode.com/v2/syncengine/synclog/3" type="html" />
  <id>http://api.obexcode.com/v2/syncengine/synclog/3</id>
  <link href="http://api.obexcode.com/v2/syncengine/synclog/3" rel="self" />
  <link href="http://api.obexcode.com/v2/syncengine/synclog/3" rel="alternate" type="text/html" />
  <published>2009-03-19T09:52:28Z</published>
  <title>syncml - google</title>
  <sync_stats xmlns="http://schemas.obexcode.com/syncserver/2009">
    <duplicates_detected>0</duplicates_detected>
    <duplicates_removed>0</duplicates_removed>
    <conflicts_detected>0</conflicts_detected>
    <source>
      <sync_source type="syncml" />
      <statistics>
        <adds_in>5</adds_in>
        <replaces_in>0</replaces_in>
        <deletes_in>0</deletes_in>
        <adds_out>4</adds_out>
        <replaces_out>0</replaces_out>
        <deletes_out>0</deletes_out>
      </statistics>
    </source>
    <target>
      <sync_source type="google" />
      <statistics>
        <adds_in>4</adds_in>
        <replaces_in>0</replaces_in>
        <deletes_in>0</deletes_in>
        <adds_out>5</adds_out>
        <replaces_out>0</replaces_out>
        <deletes_out>0</deletes_out>
      </statistics>
    </target>
  </sync_stats>
  <sync_mode xmlns="http://schemas.obexcode.com/syncserver/2009">201</sync_mode>
  <dataclass>Contacts</dataclass>
</entry>