How to create a new phone to datastore binding

This document describes the procedure used to create a new binding for a SyncML phone to a new or existing datastore account.

REST Endpoints

The following REST endpoints can be used to access phone to datastore bindings.

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

Authentication

This API is protected and need authentication. See OAuth documentation for details.

Phone Datastore atom entry

The following xml is used when registering or listing bindings between syncml and datastore:

<entry xmlns="http://www.w3.org/2005/Atom"
       xmlns:oc="http://schemas.obexcode.com/syncserver/2009">
  <id></id>
  <link href="http://api.obexcode.com/v2/syncengine/phone_datastore_bindings/187" rel="self" />
  <link href="http://api.obexcode.com/v2/syncengine/phone_datastore_bindings/187" rel="alternate" type="text/html" />
  <link href="http://api.obexcode.com/v2/services/syncml/b96afa84-a153-11de-aae5-002215064801" rel="syncml_client" type="application/atom+xml" />
  <link href="http://api.obexcode.com/v2/services/datastore/fe6b3dae-7dc9-11de-8114-002215064801" rel="datastore_client" type="application/atom+xml" />
  <oc:model_uuid></oc:model_uuid>
  <oc:phone_number></oc:phone_number>
  <oc:foreign_user_id></oc:foreign_user_id>
  <oc:timezone></oc:timezone>
</entry>

The parameters are as follows:

id: Element id. This is not sent when registering a new binding, but is returned when the binding is created, and when listing existing bindings.
link(s): Not sent when registering. The atom Links contains relevant links for the registered binding. Each link is marked with a "rel" attribute describing the relevance to the object.; self: Link to to the created binding.; alternate: HTML representation of the binding.; syncml_client: The URL of the Syncml client created when registering this binding. Should it be necessary to list details for the Syncml client, this is the URL to check.; datastore_client: The URL of the Datastore client created when registering this binding. use this to get information for the datastore client. To list the contents stored in the datastore, append "/contents/" to this URL. See the datastore API for more information.
model_uuid: UUID for the user registered phone model. Model UUIDs are found in the [phone model feed] (phones).
phone_number: The user's phone number. Must include country code. ie: "+4798765432" or "+15553334444". (Or even "+1 (555) 333-4444")
foreign_user_id: The user id on the vendor service. This is only used to allow a user to register multiple phones to the same datastore. If a phone is registered to a foreign_user_id that already exist in the datastore, the binding will be to the existing datastore, allowing the user to sync a new phone with her existing data.; The foreign user id can be any string with a maximum of 255 characters. Just make sure it is unique for each of the vendor's users.
timezone: The default timezone for the phone. This is used if the phone does not specify it's timezone when synchronizing. If not specified, the timezone for the registering syncserver user will be used.
author: Not provided when registering, only returned. Gives the name and email of the syncserver user that registered the binding.
published: Time of registration of the binding. Will be automatically set when registering.
updated: Time of last modification of the binding. Will be automatically set when registering. (Currently this should always be the same as the published time.)

Registering the binding

Post the constructed Atom entry to the controller:

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

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

The response will be the newly created entry, with any automatic fields added.

HTTP/1.1 201 Created
Date: Mon, 14 Sep 2009 17:26:23 GMT
Content-Length: 1198
Content-Type: application/atom+xml
Allow: GET, HEAD, POST
Server: CherryPy/3.1.2

<entry xmlns="http://www.w3.org/2005/Atom">
  <author>
    <name>test</name>
    <email>test@obexcode.com</email>
  </author>
  <id>http://api.obexcode.com/v2/syncengine/phone_datastore_bindings/187</id>
  <link href="http://api.obexcode.com/v2/syncengine/phone_datastore_bindings/187" rel="self" />
  <link href="http://api.obexcode.com/v2/syncengine/phone_datastore_bindings/187" rel="alternate" type="text/html" />
  <link href="http://api.obexcode.com/v2/services/syncml/b96afa84-a153-11de-aae5-002215064801" rel="syncml_client" type="application/atom+xml" />
  <link href="http://api.obexcode.com/v2/services/datastore/fe6b3dae-7dc9-11de-8114-002215064801" rel="datastore_client" type="application/atom+xml" />
  <published>2009-09-14T19:26:23Z</published>
  <title>187</title>
  <updated>2009-09-14T19:26:23Z</updated>
  <foreign_user_id xmlns="http://schemas.obexcode.com/syncserver/2009">my_user:1456</foreign_user_id>
  <phone_number xmlns="http://schemas.obexcode.com/syncserver/2009">+4799988877</phone_number>
  <model_uuid xmlns="http://schemas.obexcode.com/syncserver/2009">02978288-537f-102b-beff-000ea60275d1</model_uuid>
  <timezone xmlns="http://schemas.obexcode.com/syncserver/2009">Europe/Oslo</timezone>
</entry>

Here is a complete code example in Python.

Listing bindings

Request:

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

Response:

HTTP/1.1 200 Created
Content-Type: application/atom+xml
Content-Length: 2788

<feed xmlns="http://www.w3.org/2005/Atom">
  <author>
    <name>ObexCode AS</name>
  </author>
  <id>http://api.obexcode.com/v2/syncengine/phone_datastore_bindings/all.xml</id>
  <link href="http://api.obexcode.com/v2/syncengine/phone_datastore_bindings/all.xml" rel="self" />
  <title>Phone datastore bindings</title>
  <entry>
    <author>
      <name>admin</name>
      <email>frank@obexcode.com</email>
    </author>
    <id>http://api.obexcode.com/v2/syncengine/phone_datastore_bindings/5</id>
    <link href="http://api.obexcode.com/v2/syncengine/phone_datastore_bindings/5" rel="self" />
    <link href="http://api.obexcode.com/v2/syncengine/phone_datastore_bindings/5" rel="alternate" type="text/html" />
    <link href="http://api.obexcode.com/v2/services/syncml/2e3b9838-29bc-11de-a8bb-002215064801" rel="syncml_client" type="application/atom+xml" />
    <link href="http://api.obexcode.com/v2/services/datastore/2e3be5a4-29bc-11de-a8bb-002215064801" rel="datastore_client" type="application/atom+xml" />
    <published />
    <title>5</title>
    <updated />
    <foreign_user_id xmlns="http://schemas.obexcode.com/syncserver/2009">my_user:1456</foreign_user_id>
    <phone_number xmlns="http://schemas.obexcode.com/syncserver/2009">+4790066951</phone_number>
    <model_uuid xmlns="http://schemas.obexcode.com/syncserver/2009">2f0fd4a4-f113-11dd-a003-000e0cc4a82b</model_uuid>
    <timezone xmlns="http://schemas.obexcode.com/syncserver/2009">Europe/Oslo</timezone>
  </entry>
  <entry>
    <author>
      <name>admin</name>
      <email>frank@obexcode.com</email>
    </author>
    <id>http://api.obexcode.com/v2/syncengine/phone_datastore_bindings/12</id>
    <link href="http://api.obexcode.com/v2/syncengine/phone_datastore_bindings/12" rel="self" />
    <link href="http://api.obexcode.com/v2/syncengine/phone_datastore_bindings/12" rel="alternate" type="text/html" />
    <link href="http://api.obexcode.com/v2/services/syncml/d0d68c44-29ba-11de-ae4e-002215064801" rel="syncml_client" type="application/atom+xml" />
    <link href="http://api.obexcode.com/v2/services/datastore/bfb85fc8-30a9-11de-b930-002215064801" rel="datastore_client" type="application/atom+xml" />
    <published />
    <title>12</title>
    <updated />
    <foreign_user_id xmlns="http://schemas.obexcode.com/syncserver/2009">jallalabba</foreign_user_id>
    <phone_number xmlns="http://schemas.obexcode.com/syncserver/2009">+4790066951</phone_number>
    <model_uuid xmlns="http://schemas.obexcode.com/syncserver/2009">2f0fd4a4-f113-11dd-a003-000e0cc4a82b</model_uuid>
    <timezone xmlns="http://schemas.obexcode.com/syncserver/2009">Europe/Oslo</timezone>
  </entry>
</feed>