ObexCode Logo ObexCode Logo

Developer Zone

Table of Contents

Datastore

The Datastore is where we store users' content data. This is essentially one large list of contents, belonging to Datastore clients. The Datastore behaves like another synchronization service, but stores the data locally instead of sending it to a third party server.

Please note that the API described in this document is still pending.

REST Endpoints

The following REST endpoints can are used to access Datastore data.

API Endpoint Supported Operations
Clients http://api.obexcode.com/v2/services/datastore/ GET, POST
Content http://api.obexcode.com/v2/services/datastore/content/ GET, POST, PUT, DELETE

Authentication

The datastore API is protected and needs authentication. See OAuth documentation for details.

Clients

Like the other synchronization services, the datastore separates its data depending on "clients". Each end user account needs to be registered as a new unique client in order to avoid mixing user data.

Datastore clients can be added through the direct manipulation interface, or implicitly using the Phone Datastore Binding API. For services that will only sync phones to datastores, we advice to use the latter interface.

REST Endpoint

The endpoint for managing datastore clients is found on the following URL:

http://api.obexcode.com/v2/services/datastore/

Get list of clients

Request:

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

Response:

<feed xmlns="http://www.w3.org/2005/Atom">
  <author>
    <name>ObexCode AS</name>
  </author>
  <id>http://api.obexcode.com/v2/services/datastore/</id>
  <link href="http://api.obexcode.com/v2/services/datastore/" rel="self" />
  <title>Datastore Clients</title>
  <updated />
  <entry>
    <author>
      <name>admin</name>
      <email>support@obexcode.com</email>
    </author>
    <content type="text">Content lines: 33</content>
    <id>urn:uuid:2e3be5a4-29bc-11de-a8bb-002215064801</id>
    <link href="http://api.obexcode.com/v2/services/datastore/2e3be5a4-29bc-11de-a8bb-002215064801" rel="self" />
    <link href="http://api.obexcode.com/v2/services/datastore/2e3be5a4-29bc-11de-a8bb-002215064801" rel="alternate" type="text/html" />
    <published />
    <title>my_user:1456</title>
    <updated />
    <client xmlns="http://schemas.obexcode.com/syncserver/2009">
      <uuid>2e3be5a4-29bc-11de-a8bb-002215064801</uuid>
      <user_id>my_user:1456</user_id>
    </client>
  </entry>
</feed>

Create a new client

Request:

POST /v2/services/datastore/ 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:user_id>unique.user.id@perhaps.an.email.addr</oc:user_id>
  </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 type="text" />
  <id>http://api.obexcode.com/v2/services/datastore/99888888-9ed7-11de-a050-002215064795</id>
  <link href="http://api.obexcode.com/v2/services/datastore/99888888-9ed7-11de-a050-002215064795" rel="self" />
  <link href="http://api.obexcode.com/v2/services/datastore/99888888-9ed7-11de-a050-002215064795" rel="alternate" type="text/html" />
  <published>2009-09-22T08:08:00Z</published>
  <title>99888888-9ed7-11de-a050-002215064795</title>
  <updated>2009-09-22T08:08:00Z</updated>
  <client xmlns="http://schemas.obexcode.com/syncserver/2009">
    <uuid>99888888-9ed7-11de-a050-002215064795</uuid>
    <user_id>unique.user.id@perhaps.an.email.addr</user_id>
  </client>
</entry>

Contents

The contents endpoint is used to list a client's current datastore contents.

REST Endpoint

The endpoint for managing datastore contents is found on the following URL:

http://api.obexcode.com/v2/services/datastore/contents/

Authentication

In addition to the basic requirement for authentication, the content list requires that content for a specific client is requested. Hence it does not allow listing content for all clients at the same time.

Tests are also done to ensure that content is not shown or manipulated for clients not belonging to the currently authenticated user.

Get entire content list

Default behaviour is to retreive the entire content list for the client. This will include all classes of data, and the data may appear in no particular order.

Request:

GET /v2/services/datastore/2e3be5a4-29bc-11de-a8bb-002215064801/contents/ HTTP/1.1
Host: api.obexcode.com
Content-Type: application/atom+xml

Response:

Content feed

Get specific dataclass

For most applications it makes more sense to fetch only a specific dataclass. This can be specified with an additional parameter, "dataclass".

Available dataclasses are:

Contacts
Contact list, typically vCards
Tasks
Task list. These are vCalendar VTODO entries.
Events
Event list. These are vCalendar VEVENT entries.
Calendar
Composition of Tasks and Events. Applications that support both tasks and events at the same time should use this.
Notes
Notes. Usually plain text, but for some devices vNotes might be available here.
all
All of the above. This is the same as not specifying a dataclass.

Request:

GET /v2/services/datastore/2e3be5a4-29bc-11de-a8bb-002215064801/contents/?dataclass=Notes HTTP/1.1
Host: api.obexcode.com
Content-Type: application/atom+xml

Response:

<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Your Notes</title>
  <entry>
    <content type="text/plain">SURSUM CORDA
DEUS CARIBIS
STELLA MARIS</content>
    <title>SURSUM CORDA</title>
  </entry>
  <entry>
    <content type="text/plain">18 meter h&#195;&#184;y
10 meter bredt p&#195;&#165; feltet.</content>
    <title>18 meter h&#195;&#184;y</title>
  </entry>
</feed>

Get specific content item

A specific content item can be requested by providing the content UUID in the URL.

Request:

GET /v2/services/datastore/2e3be5a4-29bc-11de-a8bb-002215064801/contents/2e3be5a4-29bc-11de-a8bb-006677064801 HTTP/1.1
Host: api.obexcode.com
Content-Type: application/atom+xml

Response:

<entry>
  <content type="text/plain">SURSUM CORDA
DEUS CARIBIS
STELLA MARIS</content>
  <title>SURSUM CORDA</title>
</entry>

Create a new item

Creating a new item in the datastore is done by POSTing it to the endpoint. The created object will be echoed back with additional information added.

Request:

POST /v2/services/datastore/2e3be5a4-29bc-11de-a8bb-002215064801/contents/ HTTP/1.1
Host: api.obexcode.com
Content-Type: application/atom+xml

<entry>
  <content type="text/plain">SURSUM CORDA
DEUS CARIBIS
STELLA MARIS</content>
  <title>SURSUM CORDA</title>
</entry>

Response:

<entry>
  <content type="text/plain">SURSUM CORDA
DEUS CARIBIS
STELLA MARIS</content>
  <title>SURSUM CORDA</title>
</entry>

Update an item

Update an item by doing an HTTP PUT on the endpoint for that specific item. The updated object is echoed back in the response.

Request:

PUT /v2/services/datastore/2e3be5a4-29bc-11de-a8bb-002215064801/contents/2e3be5a4-29bc-11de-a8bb-006677064801 HTTP/1.1
Host: api.obexcode.com
Content-Type: application/atom+xml

<entry>
  <content type="text/plain">SURSUM CORDA
DEUS CARIBIS
STELLA MARIS</content>
  <title>SURSUM CORDA</title>
</entry>

Response:

<entry>
  <content type="text/plain">SURSUM CORDA
DEUS CARIBIS
STELLA MARIS</content>
  <title>SURSUM CORDA</title>
</entry>

Delete an item

Delete an item by doing an HTTP DELETE on the endpoint for that specific item. Only response headers are returned.

Request: 

DELETE /v2/services/datastore/2e3be5a4-29bc-11de-a8bb-002215064801/contents/2e3be5a4-29bc-11de-a8bb-006677064801 HTTP/1.1
Host: api.obexcode.com
Content-Type: application/atom+xml

Response:

HTTP/1.1 200 Deleted

Batch operation

The datastore supports batch operation both when fetching data from the datastore, and when inserting changes to the datastore. Batch operation uses a feed where each entry specify the operation to be done for the corresponding element.

Fetch batch feed

To get a batch feed from the content list, add the "since" parameter to the GET request like this:

Request:

GET /v2/services/datastore/2e3be5a4-29bc-11de-a8bb-002215064801/contents/?since=2009-09-15T12:56:31 HTTP/1.1
Host: api.obexcode.com
Content-Type: application/atom+xml

Response:

Content batch feed

This will return a feed with all changes in the datastore since the specified time. Unlike the normal content listing, this will also include deletes for objects no longer present in the datastore.

Post a batch feed

While fetching a batch feed can be done using the normal REST endpoint, posting a batch feed must be done using a separate function. A batch feed must be posted as follows:

Request:

GET /v2/services/datastore/2e3be5a4-29bc-11de-a8bb-002215064801/contents/batch?dataclass=Contacts HTTP/1.1
Host: api.obexcode.com
Content-Type: application/atom+xml

<feed xmlns="http://www.w3.org/2005/Atom"
  xmlns:oc="http://schemas.obexcode.com/syncserver/2009"
  xmlns:batch="http://schemas.google.com/gdata/batch">
  <entry>
    <oc:content dataclass="Contacts" type="text/x-vcard">BEGIN:VCARD
VERSION:2.1
N;CHARSET=ISO-8859-1;ENCODING=QUOTED-PRINTABLE:D=F8ckers;D=F8lly
TEL;CELL;PREF:+4712345678
END:VCARD</oc:content>
    <title>D&#248;lly D&#248;ckers</title>
    <batch:operation type="insert" />
    <batch:id>Inserted_0001</batch:id>
  </entry>
  <entry>
    <id>urn:uuid:8589d6b8-a2bb-11de-b877-002215064801</id>
    <title>D&#248;lle Deleter</title>
    <batch:operation type="delete" />
    <batch:id>Deleted_0001</batch:id>
  </entry>
</feed>

Response:

HTTP/1.1 200 OK
Date: Wed, 16 Sep 2009 12:21:55 GMT
Content-Length: 2166
Content-Type: application/atom+xml
Server: CherryPy/3.1.2

<feed xmlns="http://www.w3.org/2005/Atom">
  <author>
    <name>Nosy Test Guy</name>
  </author>
  <id>http://api.obexcode.com/v2/services/datastore/844c88d6-a2bb-11de-b877-002215064801/contents/batch</id>
  <link href="http://api.obexcode.com/v2/services/datastore/844c88d6-a2bb-11de-b877-002215064801/contents/batch" rel="self" />
  <title>Batch results</title>
  <entry>
    <author>
      <name>my_user:1456</name>
    </author>
    <content dataclass="Contacts" type="text/x-vcard" xmlns="http://schemas.obexcode.com/syncserver/2009">BEGIN:VCARD
VERSION:2.1
N;CHARSET=ISO-8859-1;ENCODING=QUOTED-PRINTABLE:D=F8ckers;D=F8lly
TEL;CELL;PREF:+4712345678
END:VCARD</content>
    <id>urn:uuid:859c2836-a2bb-11de-b877-002215064801</id>
    <link href="http://api.obexcode.com/v2/services/datastore/844c88d6-a2bb-11de-b877-002215064801/contents/859c2836-a2bb-11de-b877-002215064801" rel="self" />
    <published>2009-09-16T14:21:55Z</published>
    <title>D&#248;lly D&#248;ckers</title>
    <updated>2009-09-16T14:21:55Z</updated>
    <id xmlns="http://schemas.google.com/gdata/batch">Inserted_0001</id>
    <status code="201" reason="Created" xmlns="http://schemas.google.com/gdata/batch" />
    <operation type="insert" xmlns="http://schemas.google.com/gdata/batch" />
  </entry>
  <entry>
    <author>
      <name>my_user:1456</name>
    </author>
    <content dataclass="Contacts" type="text/x-vcard" xmlns="http://schemas.obexcode.com/syncserver/2009">BEGIN:VCARD
VERSION:2.1
N;CHARSET=ISO-8859-1;ENCODING=QUOTED-PRINTABLE:D=F8ck;D=F8lle
TEL;CELL;PREF:+4712345678
END:VCARD</content>
    <id>urn:uuid:8589d6b8-a2bb-11de-b877-002215064801</id>
    <link href="http://api.obexcode.com/v2/services/datastore/844c88d6-a2bb-11de-b877-002215064801/contents/8589d6b8-a2bb-11de-b877-002215064801" rel="self" />
    <published>2009-09-16T14:21:55Z</published>
    <title>D&#248;lle D&#248;ck</title>
    <updated>2009-09-16T14:21:55Z</updated>
    <id xmlns="http://schemas.google.com/gdata/batch">Deleted_0001</id>
    <status code="200" reason="Deleted" xmlns="http://schemas.google.com/gdata/batch" />
    <operation type="delete" xmlns="http://schemas.google.com/gdata/batch" />
  </entry>
</feed>

The batch response feed contains a response entry for each entry in the posted feed, providing updated data as well as response codes.