ObexCode Logo ObexCode Logo

Developer Zone

Table of Contents

Google Data Client API

The Google Data Client API is used for registering sync sources based on the public Google API specification. It enables the sync server to synchronize with GMail contacts and Google Calendar. In addition this is the preferred method for synchronizing with external datastores.

External datastores implementing a GData interface should register google data clients using the POST method of this API, complete with access tokens. After registering, the client should be connected as described in the Sync Engine guide.

Authorization

The Google Data Client API requires authentication. No listing or updates is allowed to anonymous request. Further, operations are of course only allowed on objects belonging to the current user account.

REST End points

There is just a single endpoint for google clients. In the future, endpoints for datastores and tokens may be added below this endpoint.

API Endpoint Supported Operations
Client http://api.obexcode.com/v2/services/google/ GET, POST, PUT, DELETE

XML Object description

The Google Client ATOM entry from the syncserver typically looks like the listing below.

<entry xmlns="http://www.w3.org/2005/Atom">
  <!-- Standard ATOM Author entry -->
  <author>
    <name>admin</name>
    <email>support@obexcode.com</email>
  </author>
  <!-- ATOM id is the URL to the element.  This is repeated for several of the links as well -->
  <id>http://api.obexcode.com/v2/services/google/4f1d2dd0-49e4-11de-b387-002215064801</id>
  <link href="http://api.obexcode.com/v2/services/google/4f1d2dd0-49e4-11de-b387-002215064801" rel="self" />
  <link href="http://api.obexcode.com/v2/services/google/4f1d2dd0-49e4-11de-b387-002215064801/edit" rel="edit" />
  <link href="http://api.obexcode.com/v2/services/google/4f1d2dd0-49e4-11de-b387-002215064801" rel="alternate" type="text/html" />

  <!-- Creation time (published) and modification time. -->
  <published>2009-05-26T12:59:39Z</published>
  <updated>2009-05-26T13:09:47Z</updated>

  <!-- Title will be set to the user id of the GData user.  Content is
    provided only as a reference to the content data on the server. -->
  <title>some_user@gmail.com</title>
  <content src="http://api.obexcode.com/v2/services/google/4f1d2dd0-49e4-11de-b387-002215064801" type="html" />

  <!-- The client object contains the actual client data. -->
  <client xmlns="http://schemas.obexcode.com/syncserver/2009">

    <!-- The UUID is generated when registering the client.  It cannot be
         changed later. -->
    <uuid>4f1d2dd0-49e4-11de-b387-002215064801</uuid>

    <!-- The user id on the GData server. -->
    <user_id>some_user@gmail.com</user_id>

    <!-- The datastore specification describes each available datastore for
      synchronization.  The "dataclass" and "href" attributes are mandatory,
      the "name" attribute can be omitted, in which case the "dataclass"
      will be used as "name".  There must be one datastore definition for
      each supported dataclass. -->
    <datastore dataclass="Calendar" href="http://www.google.com/calendar/feeds/e0an755fcc57j0a25ptli0d22g%40group.calendar.google.com/private/full" name="Test">

      <!-- The token field show the currently associated token for the datastore.
        Type is 1 - Request token or 2 - Access token.  If the datastore is
        registered directly with an access token, the need for a full OAuth
        authentication cycle may be omitted. -->
      <token>
        <type>2</type>

        <!-- Scopes define where the token is valid. -->
        <scope>https://www.google.com/calendar/feeds/</scope>
        <scope>http://www.google.com/calendar/feeds/</scope>

        <!-- The "key" and "secret" fields are only used when registering or
          updating the client.  It is not revealed when listing the client. -->
        <key>secret_key</key>
        <secret>secret_secret</secret>
      </token>
    </datastore>
    <datastore dataclass="Contacts" href="http://www.google.com/m8/feeds/groups/some_user%40gmail.com/base/7d2f83ef088611c8" name="Test">
      <token>
        <type>2</type>
        <scope>https://www.google.com/m8/feeds/</scope>
        <scope>http://www.google.com/m8/feeds/</scope>
      </token>
    </datastore>
  </client>
</entry>

List all clients

To list all clients, use HTTP GET directly on the REST endpoint. This will list all clients belonging to the currently authenticated account.

Possible responses

200 OK
Response contain list of clients. List may be empty.

Example

Request:

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

Response:

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

<feed xmlns="http://www.w3.org/2005/Atom">
  <author>
    <name>ObexCode AS</name>
  </author>
  <id>http://api.obexcode.com/v2/services/google/all.xml</id>
  <link href="http://api.obexcode.com/v2/services/google/all.xml" rel="self" />
  <title>Google Data Clients</title>
  <updated>2009-05-26T13:09:47Z</updated>
  <entry>
    <author>
      <name>admin</name>
      <email>support@obexcode.com</email>
    </author>
    <content src="http://api.obexcode.com/v2/services/google/4f1d2dd0-49e4-11de-b387-002215064801" type="html" />
    <id>http://api.obexcode.com/v2/services/google/4f1d2dd0-49e4-11de-b387-002215064801</id>
    <link href="http://api.obexcode.com/v2/services/google/4f1d2dd0-49e4-11de-b387-002215064801" rel="self" />
    <link href="http://api.obexcode.com/v2/services/google/4f1d2dd0-49e4-11de-b387-002215064801/edit" rel="edit" />
    <link href="http://api.obexcode.com/v2/services/google/4f1d2dd0-49e4-11de-b387-002215064801" rel="alternate" type="text/html" />
    <published>2009-05-26T12:59:39Z</published>
    <title>some_user@gmail.com</title>
    <updated>2009-05-26T13:09:47Z</updated>
    <client xmlns="http://schemas.obexcode.com/syncserver/2009">
      <uuid>4f1d2dd0-49e4-11de-b387-002215064801</uuid>
      <user_id>some_user@gmail.com</user_id>
      <datastore dataclass="Calendar" href="http://www.google.com/calendar/feeds/e0an755fcc57j0a25ptli0d22g%40group.calendar.google.com/private/full" name="Test">
        <token>
          <type>2</type>
          <scope>https://www.google.com/calendar/feeds/</scope>
          <scope>http://www.google.com/calendar/feeds/</scope>
        </token>
      </datastore>
      <datastore dataclass="Contacts" href="http://www.google.com/m8/feeds/groups/some_user%40gmail.com/base/7d2f83ef088611c8" name="Test">
        <token>
          <type>2</type>
          <scope>https://www.google.com/m8/feeds/</scope>
          <scope>http://www.google.com/m8/feeds/</scope>
        </token>
      </datastore>
    </client>
  </entry>
</feed>

Get details for specific client

To get details for a specific client, use HTTP GET in the entry URI.

Possible responses

200 OK
Response contains the client details.
403 Forbidden
Attempt at fetching details from another user.
404 No such Google client.
Provided client id does not exist.

Example

Request:

GET /v2/services/google/4f1d2dd0-49e4-11de-b387-002215064801/ HTTP/1.1
Host: api.obexcode.com
Accept: application/atom+xml

Response:

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

<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/google/4f1d2dd0-49e4-11de-b387-002215064801" type="html" />
  <id>http://api.obexcode.com/v2/services/google/4f1d2dd0-49e4-11de-b387-002215064801</id>
  <link href="http://api.obexcode.com/v2/services/google/4f1d2dd0-49e4-11de-b387-002215064801" rel="self" />
  <link href="http://api.obexcode.com/v2/services/google/4f1d2dd0-49e4-11de-b387-002215064801/edit" rel="edit" />
  <link href="http://api.obexcode.com/v2/services/google/4f1d2dd0-49e4-11de-b387-002215064801" rel="alternate" type="text/html" />
  <published>2009-05-26T12:59:39Z</published>
  <title>some_user@gmail.com</title>
  <updated>2009-05-26T13:09:47Z</updated>
  <client xmlns="http://schemas.obexcode.com/syncserver/2009">
    <uuid>4f1d2dd0-49e4-11de-b387-002215064801</uuid>
    <user_id>some_user@gmail.com</user_id>
    <datastore dataclass="Calendar" href="http://www.google.com/calendar/feeds/e0an755fcc57j0a25ptli0d22g%40group.calendar.google.com/private/full" name="Test">
      <token>
        <type>2</type>
        <scope>https://www.google.com/calendar/feeds/</scope>
        <scope>http://www.google.com/calendar/feeds/</scope>
      </token>
    </datastore>
    <datastore dataclass="Contacts" href="http://www.google.com/m8/feeds/groups/some_user%40gmail.com/base/7d2f83ef088611c8" name="Test">
      <token>
        <type>2</type>
        <scope>https://www.google.com/m8/feeds/</scope>
        <scope>http://www.google.com/m8/feeds/</scope>
      </token>
    </datastore>
  </client>
</entry>

Add a new client

Adding a new client is done with the HTTP POST method to the REST end point.

Possible responses

201 Created
Client created successfully. Response will contain the client entry including any default data that was not provided in the request.
400 No Entry provided
Must have some data to create.
400 Google client already registered
The supplied user id already exists. Only one client registration per end user.

Example

Request:

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

<entry xmlns="http://www.w3.org/2005/Atom">
  <client xmlns="http://schemas.obexcode.com/syncserver/2009">
    <user_id>some_user@gmail.com</user_id>
    <datastore dataclass="Calendar" href="http://google_something.com/some_user@gmail.com/calendar#Test" name="Calendar">
      <token>
        <token_type>2</token_type>
        <key>secret_key</key>
        <secret>secret_secret</secret>
        <scope>http://google_something.com/some_user@gmail.com/calendar#Test</scope>
      </token>
    </datastore>
  </client>
</entry>

Response:

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

<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/google/51579fd6-01a5-11de-8505-002215064801" type="html" />
  <id>http://api.obexcode.com/v2/services/google/51579fd6-01a5-11de-8505-002215064801</id>
  <link href="http://api.obexcode.com/v2/services/google/51579fd6-01a5-11de-8505-002215064801" rel="self" />
  <link href="http://api.obexcode.com/v2/services/google/51579fd6-01a5-11de-8505-002215064801/edit" rel="edit" />
  <link href="http://api.obexcode.com/v2/services/google/51579fd6-01a5-11de-8505-002215064801" rel="alternate" type="text/html" />
  <published>2009-02-23T13:27:21Z</published>
  <title>some_user@gmail.com</title>
  <updated>2009-02-23T13:27:21Z</updated>
  <client xmlns="http://schemas.obexcode.com/syncserver/2009">
    <uuid>51579fd6-01a5-11de-8505-002215064801</uuid>
    <user_id>some_user@gmail.com</user_id>
    <datastore dataclass="Calendar" href="http://google_something.com/some_user@gmail.com/calendar#Test" name="Calendar">
      <token>
        <token_type>2</token_type>
        <key>secret_key</key>
        <secret>secret_secret</secret>
        <scope>http://google_something.com/some_user@gmail.com/calendar#Test</scope>
      </token>
    </datastore>
  </client>
</entry>

Update a client

Updating a client is used to add datastores to the client. In the future other parameters may be updated as well. Update is done using the HTTP PUT method. The updated client entry is returned in the response.

Possible responses

200 Updated
Client data updated successfully. Response will contain the updated client entry.
400 No client ID provided
The update request must be performed on a specific ID. This should be in the URI of the request, but will be looked for in the entry->client->uuid if not.
400 No Entry provided
Must have some data to update with.
403 Forbidden
Attempt at updating a client that does not belong to the authenticated user.
404 No such client ID
The provided ID does not exist.

Example

Request:

PUT /v2/services/google/51579fd6-01a5-11de-8505-002215064801/ 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>some_user@gmail.com</oc:user_id>
    <oc:datastore dataclass="Contacts" href="http://google_something.com/some_user@gmail.com#Friends" name="Contacts">
      <oc:token>
        <oc:token_type>2</oc:token_type>
        <oc:key>secret_key</oc:key>
        <oc:secret>secret_secret</oc:secret>
        <oc:scope>http://google_something.com/some_user@gmail.com#Friends</oc:scope>
      </oc:token>
    </oc:datastore>
  </oc:client>
</entry>

Response:

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

<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/google/51579fd6-01a5-11de-8505-002215064801" type="html" />
  <id>http://api.obexcode.com/v2/services/google/51579fd6-01a5-11de-8505-002215064801</id>
  <link href="http://api.obexcode.com/v2/services/google/51579fd6-01a5-11de-8505-002215064801" rel="self" />
  <link href="http://api.obexcode.com/v2/services/google/51579fd6-01a5-11de-8505-002215064801/edit" rel="edit" />
  <link href="http://api.obexcode.com/v2/services/google/51579fd6-01a5-11de-8505-002215064801" rel="alternate" type="text/html" />
  <published>2009-02-23T13:27:21Z</published>
  <title>some_user@gmail.com</title>
  <updated>2009-02-23T13:27:21Z</updated>
  <client xmlns="http://schemas.obexcode.com/syncserver/2009">
    <uuid>51579fd6-01a5-11de-8505-002215064801</uuid>
    <user_id>some_user@gmail.com</user_id>
    <datastore dataclass="Calendar" href="http://google_something.com/some_user@gmail.com#Test">Calendar</datastore>
    <datastore dataclass="Contacts" href="http://google_something.com/some_user@gmail.com#Friends">Contacts</datastore>
  </client>
</entry>

Delete a client

Deleting a client is done using the HTTP DELETE method on the REST Endpoint. The response contains no data. The HTTP response code will tell if the operation was successful.

Possible responses

200 Deleted
Client and data properly deleted.
400 No client ID provided
The delete request must be performed on a specific ID.
403 Forbidden
Attempt at deleting a client that does not belong to the authenticated user.
404 No such client ID
The provided ID does not exist.

Example

Request:

DELETE /v2/services/google/51579fd6-01a5-11de-8505-002215064801/ HTTP/1.1
Host: api.obexcode.com

Response:

HTTP/1.1 200 Deleted

Google Server Implementation

ObexCode does not currently provide an example implementation of the Google Data serverside API. Our solution uses the Google Data API module from Google. Below we lists the relevant functionality currently used when synchronizing.

Contact functions

The following functions are used when synchronizing contacts.

GetContactsFeed
Required. The main function for fetching the contact feed.
CreateContact
Required. Used for adding a new contact on the GData server.
UpdateContact
Required. Used for updating a contact.
DeleteContact
Required. Delete a contact.
GetGroupsFeed
Optional. Only used when listing available contact groups for the user. Not directly required for synchronizing if the server does not implement groups, all contacts should be synchronized or the datastore URL provided already identifies the group.

Calendar functions

The following functions are used when synchronizing calendars.

GetCalendarEventFeed
Required. Used for fetching the events from the calendar.
InsertEvent
Required.
UpdateEvent
Required.
DeleteEvent
Required.
GetCalendarListFeed
Optional.