ObexCode Logo ObexCode Logo

Developer Zone

Table of Contents

SyncML API

Open Mobile Alliance Data Synchronization also called SyncML is a mobile phone synchronization standard supported by most Nokia, Sony Ericsson and Samsung mobile phones.

The SyncML API gives access to directly registering, listing and deleting SyncML clients, usually phones. It also provides a few sub-APIs to send synchronization settings to phones, server initiated sync and listing SyncML sessions and registered datastores.

REST Endpoints

The following REST endpoints are used by the SyncML API

API Endpoint Supported Operations
Clients http://api.obexcode.com/v2/services/syncml/ GET, POST, DELETE
Setup http://api.obexcode.com/v2/services/syncml/setup/ POST
Sessions http://api.obexcode.com/v2/services/syncml/sessions/ GET
Datastores http://api.obexcode.com/v2/services/syncml/datastores/ GET

Authentication

Accessing the details of the SyncML clients requires authentication. Even with authentication, only the clients of the authenticated user will be accessible.

SyncML Client API

The SyncML Client API is used for manipulating registered SyncML clients (phones). The client data contains the necessary details for registering and synchronizing a phone.

The lack of a PUT method for the SyncML clients makes it impossible to edit the client. This is by design, since there should not be any reason to edit the client after creation. Experience shows that the main reason users want to edit their clients is to change the model to reflect a new phone, but this causes some problems when synchronizing. New phones should be registered as such, even if the phone number stay the same.

Listing all clients

Request:

GET /v2/services/syncml/ 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: 3083

<feed xmlns="http://www.w3.org/2005/Atom">
  <author>
    <name>ObexCode AS</name>
  </author>
  <id>http://api.obexcode.com/v2/services/syncml/</id>
  <link href="http://api.obexcode.com/v2/services/syncml/" rel="self" />
  <title>SyncML Clients</title>
  <updated>2009-04-28T13:32:59Z</updated>
  <entry>
    <author>
      <name>admin</name>
      <email>support@obexcode.com</email>
    </author>
    <content src="http://api.obexcode.com/v2/services/syncml/2fb295cc-0e50-11de-81c8-002215064801" type="text/html" />
    <id>http://api.obexcode.com/v2/services/syncml/2fb295cc-0e50-11de-81c8-002215064801</id>
    <link href="http://api.obexcode.com/v2/services/syncml/2fb295cc-0e50-11de-81c8-002215064801" rel="self" />
    <link href="http://api.obexcode.com/v2/services/syncml/2fb295cc-0e50-11de-81c8-002215064801" rel="alternate" type="text/html" />
    <published>2009-03-11T16:20:42Z</published>
    <title>Nokia 5310 XpressMusic</title>
    <updated>2009-03-13T13:25:43Z</updated>
    <client xmlns="http://schemas.obexcode.com/syncserver/2009">
      <uuid>2fb295cc-0e50-11de-81c8-002215064801</uuid>
      <user_id>1</user_id>
      <datastore dataclass="Calendar" href="http://api.obexcode.com/v2/services/syncml/datastores/Calendar">Calendar</datastore>
      <datastore dataclass="Contacts" href="http://api.obexcode.com/v2/services/syncml/datastores/Contacts">Contacts</datastore>
      <phone_number>+4790981948</phone_number>
      <model_uuid>112</model_uuid>
      <imei />
      <setup sent="2009-03-13 13:25:43">SyncServer</setup>
      <timezone>Europe/Oslo</timezone>
    </client>
  </entry>
  <entry>
    <author>
      <name>admin</name>
      <email>support@obexcode.com</email>
    </author>
    <content src="http://api.obexcode.com/v2/services/syncml/bfb81234-30a9-11de-b930-002215064801" type="text/html" />
    <id>http://api.obexcode.com/v2/services/syncml/bfb81234-30a9-11de-b930-002215064801</id>
    <link href="http://api.obexcode.com/v2/services/syncml/bfb81234-30a9-11de-b930-002215064801" rel="self" />
    <link href="http://api.obexcode.com/v2/services/syncml/bfb81234-30a9-11de-b930-002215064801" rel="alternate" type="text/html" />
    <published>2009-04-24T10:27:29Z</published>
    <title>Nokia 5800 XpressMusic</title>
    <updated>2009-04-28T13:32:59Z</updated>
    <client xmlns="http://schemas.obexcode.com/syncserver/2009">
      <uuid>bfb81234-30a9-11de-b930-002215064801</uuid>
      <user_id>1</user_id>
      <datastore dataclass="Contacts" href="http://api.obexcode.com/v2/services/syncml/datastores/Contacts">C:Contacts.cdb</datastore>
      <datastore dataclass="Notes" href="http://api.obexcode.com/v2/services/syncml/datastores/Notes">c:Notepad.dat</datastore>
      <datastore dataclass="Calendar" href="http://api.obexcode.com/v2/services/syncml/datastores/Calendar">C:Calendar</datastore>
      <phone_number>+4790066951</phone_number>
      <model_uuid>56</model_uuid>
      <imei />
      <setup sent="2009-04-24 10:30:26">NewSyncFrank</setup>
      <timezone>Europe/Oslo"</timezone>
    </client>
  </entry>
</feed>

List details for a specific client

Request:

GET /v2/services/syncml/3fe85584-12d9-11de-b2ce-002215064801 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: 1417

<entry xmlns="http://www.w3.org/2005/Atom">
  <author>
    <name>admin</name>
    <email>support@obexcode.com</email>
  </author>
  <content src="http://api.obexcode.com/v2/services/syncml/3fe85584-12d9-11de-b2ce-002215064801" type="text/html" />
  <id>http://api.obexcode.com/v2/services/syncml/3fe85584-12d9-11de-b2ce-002215064801</id>
  <link href="http://api.obexcode.com/v2/services/syncml/3fe85584-12d9-11de-b2ce-002215064801" rel="self" />
  <link href="http://api.obexcode.com/v2/services/syncml/3fe85584-12d9-11de-b2ce-002215064801" rel="alternate" type="text/html" />
  <published>2009-03-17T10:51:55Z</published>
  <title>Nokia 6233</title>
  <updated>2009-03-18T09:41:52Z</updated>
  <client xmlns="http://schemas.obexcode.com/syncserver/2009">
    <uuid>3fe85584-12d9-11de-b2ce-002215064801</uuid>
    <user_id>1</user_id>
    <datastore dataclass="Calendar" href="http://api.obexcode.com/v2/services/syncml/datastores/Calendar">Calendar</datastore>
    <datastore dataclass="Contacts" href="http://api.obexcode.com/v2/services/syncml/datastores/Contacts">Contacts</datastore>
    <datastore dataclass="Calendar" href="http://api.obexcode.com/v2/services/syncml/datastores/Calendar">cal.vcs</datastore>
    <phone_number>+4790066951</phone_number>
    <model_uuid>242</model_uuid>
    <imei />
    <setup sent="2009-03-17 14:01:01">SyncServer</setup>
    <timezone>Europe/Oslo</timezone>
  </client>
</entry>

Create a new client

Request:

POST /v2/services/syncml/ HTTP/1.1
Host: api.obexcode.com
Content-Type: application/atom+xml
Accept: application/atom+xml

<entry xmlns="http://www.w3.org/2005/Atom" xmlns:oc="http://schemas.obexcode.com/syncserver/2009">
  <oc:client>
    <oc:phone_number>+4798765432</oc:phone_number>
    <oc:model_uuid>02978288-537f-102b-beff-000ea60275d1</oc:model_uuid>
    <oc:timezone>Europe/Paris</oc:timezone>
  </oc:client>
</entry>

Response:

HTTP/1.1 201 Created
Content-Type: application/atom+xml

<entry xmlns="http://www.w3.org/2005/Atom">
  <author>
    <name>admin</name>
    <email>support@obexcode.com</email>
  </author>
  <content src="http://api.obexcode.com/v2/services/syncml/3fe85584-12d9-11de-b2ce-002215064801" type="text/html" />
  <id>http://api.obexcode.com/v2/services/syncml/3fe85584-12d9-11de-b2ce-002215064801</id>
  <link href="http://api.obexcode.com/v2/services/syncml/3fe85584-12d9-11de-b2ce-002215064801" rel="self" />
  <link href="http://api.obexcode.com/v2/services/syncml/3fe85584-12d9-11de-b2ce-002215064801" rel="alternate" type="text/html" />
  <published>2009-03-17T10:51:55Z</published>
  <title>Nokia 6233</title>
  <updated>2009-03-18T09:41:52Z</updated>
  <client xmlns="http://schemas.obexcode.com/syncserver/2009">
    <uuid>3fe85584-12d9-11de-b2ce-002215064801</uuid>
    <user_id>1</user_id>
    <phone_number>+4798765432</phone_number>
    <model_uuid>02978288-537f-102b-beff-000ea60275d1</model_uuid>
    <imei />
    <setup sent="" />
    <timezone>Europe/Paris</timezone>
  </client>
</entry>

Delete a client

Request:

DELETE /v2/services/syncml/3fe85584-12d9-11de-b2ce-002215064801 HTTP/1.1
Host: api.obexcode.com
Content-Type: application/atom+xml
Accept: application/atom+xml

Response:

HTTP/1.1 200 OK

Setup and Phone Configuration

To send synchronization setup to a SyncML client, POST a setup entry to the endpoint. Phone setup needs to be confirmed and installed on the mobile phone

REST Endpoints

API Endpoint Supported Operations
Setup http://api.obexcode.com/v2/services/syncml/setup/ POST

Code example

Request:

POST /v2/services/syncml/51d49c2c-3006-11de-afd4-002215064801/setup/ HTTP/1.1
Host: api.obexcode.com
Content-type: application/atom+xml
Content-length: 143

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

The response will be the entry with generated fields inserted.

HTTP/1.1 201 Created
Content-Type: application/atom+xml
Content-Length: 309

<entry xmlns="http://www.w3.org/2005/Atom"
       xmlns:oc="http://schemas.obexcode.com/syncserver/2009">
  <id>http://api.obexcode.com/v2/services/syncml/51d49c2c-3006-11de-afd4-002215064801/setup/143/</id>
  <oc:pincode>1234</oc:pincode>
  <oc:setup sent="2008-08-15T16:13:03Z">Mobile Backup</oc:setup>
</entry>

Server Initiated Synchronization

It's possible for the server to request a mobile phone to start synchronizing with the sever. To request synchronization of a SyncML client, POST simply make a POST to the sync endpoint.

Not all phones supports server initiated sync. Server initiated sync also needs to be confirmed on the phone. A mobile phone can however be configured to allow such sync requests autmatically.

REST Endpoints

API Endpoint Supported Operations
Sync http://api.obexcode.com/v2/services/syncml/sync/ POST

Code example

POST /v2/services/syncml/51d49c2c-3006-11de-afd4-002215064801/sync/ HTTP/1.1
Host: api.obexcode.com
Content-type: application/atom+xml
Content-length: 0

The respose will only be the HTTP status code. No content is currently being returned.

HTTP/1.1 200 Ok
Content-Type: application/atom+xml
Content-Length: 0

Session API

The session API lists the SyncML sessions done by the phone. It is mostly used for statistics and debugging failed synchronizations.

REST Endpoints

API Endpoint Supported Operations
Sessions http://api.obexcode.com/v2/services/syncml/sessions/ GET
Chatlog http://api.obexcode.com/v2/services/syncml/sessions/chatlog/ GET

Chatlog

The Chatlog is tied to the session log and can display the actual SyncML XML data received from the phone and sent back to the phone. It is only available to site administrators, and is used for debugging failed transactions.

Datastore API

Not implemented yet

The Datastore API endpoint will list information about the client datastores registered for the client. These datastores are generated on the first synchronization of the phone.

REST Endpoints

API Endpoint Supported Operations
Datastores http://api.obexcode.com/v2/services/syncml/datastores/ GET