%META:TOPICPARENT{name="Ods"}%
%ODSNAV%

%TOC%

---+ OpenSocial API support

---++ APIs supported

The ODS package contains OpenSocial data APIs about people and activities. Also it implements a login compatible with GBase which can be used to perform OpenSocial API calls requiring authentication. The implementation code is located in the opensocial.sql file from the ods package.

---++ Authentication

The authentication is compatible with GBase <nowiki>ClientLogin</nowiki> username/password authentication. 

---+++ REST API details
   * URI: http://&lt;cname>:&lt;port>/feeds/login

---+++Parameters
   * Uname - the ODS user account 
   * Passwd - password

---+++Return

   * On success it will return:
<verbatim>
auth=NNNN 
</verbatim>
where NNNN... is a security token and it matches a SID for login to ODS. 

   * If authentication fails it will return:
<verbatim>
Error=BadAuthentication
</verbatim>

---+++ Sample session

<verbatim>
$ curl -i "http://localhost/feeds/login?Uname=test&Passwd=secret"
HTTP/1.1 200 OK
Server: Virtuoso/05.00.3021 (Linux) i686-pc-linux-gnu  VDB
Connection: Keep-Alive
Date: Wed, 14 Nov 2007 16:44:42 GMT
Accept-Ranges: bytes
Content-Type: text/plain; charset="ISO-8859-1"
Content-Length: 38

auth=f305177cb1d9fbf409579250e944e980
</verbatim>


---++ People API

The people API is implemented as described in http://code.google.com/apis/opensocial/docs/gdata/people/developers_guide_protocol.html
The only difference is that personID is not a number but ODS user account.

---+++ Sample Session

---++++ Person data
<verbatim>
$ curl -i "http://localhost:8890/feeds/people/demo"
HTTP/1.1 200 OK
Server: Virtuoso/05.00.3021 (Linux) i686-pc-linux-gnu  VDB
Connection: Keep-Alive
Date: Wed, 14 Nov 2007 16:49:27 GMT
Accept-Ranges: bytes
Content-Type: application/atom+xml; charset="ISO-8859-1"
Content-Length: 1018

<entry xmlns="http://www.w3.org/2005/Atom" xmlns:georss="http://www.georss.org/georss" xmlns:gd="http://schemas.google.com/g/2005">
<id>http://localhost:8890/feeds/people/demo</id>
<updated>2007-11-01T10:55:33.000+02:00</updated>
<title>demo demo</title>
<link rel="thumbnail" type="image/*" href="/DAV/home/demo/wa/images/me_avt.jpg"/>
<link rel="alternate" type="text/html" href="http://localhost:8890/dataspace/person/demo"/>
<link rel="self" type="application/atom+xml" href="http://localhost:8890/feeds/people/demo"/>
<georss:where>
<gml:Point xmlns:gml="http://www.opengis.net/gml">
<gml:pos>43.000000 25.000000</gml:pos>
</gml:Point>
</georss:where>
<gd:extendedProperty name="lang" value="en-US"/>
<gd:postalAddress label="Home"><![CDATA[
str. 123
apt. 45
New York
USA
]]></gd:postalAddress>
<gd:postalAddress label="Work"><![CDATA[
]]></gd:postalAddress>
<gd:phoneNumber label="Private" rel="http://schemas.google.com/g/2005#mobile">+359887563204</gd:phoneNumber>
</entry>
</verbatim>

---++++ Friends
<verbatim>
$ curl -i "http://localhost:8890/feeds/people/demo/friends"
HTTP/1.1 200 OK
Server: Virtuoso/05.00.3021 (Linux) i686-pc-linux-gnu  VDB
Connection: Keep-Alive
Date: Wed, 14 Nov 2007 16:50:14 GMT
Accept-Ranges: bytes
Content-Type: application/atom+xml; charset="ISO-8859-1"
Content-Length: 2104

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/" xmlns:georss="http://www.georss.org/georss" xmlns:gd="http://schemas.google.com/g/2005">
<id>http://localhost:8890/feeds/people/demo/friends</id>
<updated>2007-11-14T18:50:14.000+02:00</updated>
<title>demo's Friends</title>
<link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="http://localhost:8890/feeds/people/demo/friends"/>
<link rel="self" type="application/atom+xml" href="http://localhost:8890/feeds/people/demo/friends"/>
<author><name>demo</name></author>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:georss="http://www.georss.org/georss" xmlns:gd="http://schemas.google.com/g/2005">
<id>http://localhost:8890/feeds/people/dav</id>
<updated>2007-11-01T10:33:10.000+02:00</updated>
<title>WebDAV System Administrator</title>
<link rel="alternate" type="text/html" href="http://localhost:8890/dataspace/person/dav"/>
<link rel="self" type="application/atom+xml" href="http://localhost:8890/feeds/people/dav"/>
<georss:where>
<gml:Point xmlns:gml="http://www.opengis.net/gml">
</gml:Point>
</georss:where>
<gd:extendedProperty name="lang" value="en-US"/>
<gd:postalAddress label="Home"><![CDATA[
]]></gd:postalAddress>
<gd:postalAddress label="Work"><![CDATA[
]]></gd:postalAddress>
</entry>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:georss="http://www.georss.org/georss" xmlns:gd="http://schemas.google.com/g/2005">
<id>http://localhost:8890/feeds/people/alice</id>
<updated>2007-11-02T18:01:04.000+02:00</updated>
<title>alice</title>
<link rel="alternate" type="text/html" href="http://localhost:8890/dataspace/person/alice"/>
<link rel="self" type="application/atom+xml" href="http://localhost:8890/feeds/people/alice"/>
<georss:where>
<gml:Point xmlns:gml="http://www.opengis.net/gml">
</gml:Point>
</georss:where>
<gd:extendedProperty name="lang" value="en-US"/>
<gd:postalAddress label="Home"><![CDATA[
(Private Address), 
]]></gd:postalAddress>
<gd:postalAddress label="Work"><![CDATA[
]]></gd:postalAddress>
</entry>
</feed>
</verbatim>

---++ Activities API

The activities API is implemented as described in http://code.google.com/apis/opensocial/docs/gdata/activities/developers_guide_protocol.html 

---+++ Creating entries

To create a new entry client must be authenticated first, then it issue a POST request to the activities feed an Atom based xml representation like :
<verbatim>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom">
  <atom:updated>2007-10-29T19:00:51.574Z</atom:updated>
  <atom:category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/activities/2007#activities"/>
  <atom:title>I'm at work</atom:title>
</atom:entry>
</verbatim>

The server will respond with entry containing atom:id element, below is a simple session for creating a new entry. The "ODS Auth" value is the sid value for the logged in user demo in ODS.

<verbatim>
curl -i -d "`cat act.xml`" -H "Authorization: ODS Auth=032a81d688a275910bd5ef31aff6d5ab" -H "Content-Type: application/atom+xml" "http://localhost:8890/activities/feeds/activities/user/demo/source/0" 
HTTP/1.1 201 Created
Server: Virtuoso/05.00.3021 (Linux) i686-pc-linux-gnu  VDB
Connection: Keep-Alive
Date: Thu, 15 Nov 2007 12:25:10 GMT
Accept-Ranges: bytes
Content-Type: application/atom+xml; charset="ISO-8859-1"
Content-Length: 636

<entry xmlns="http://www.w3.org/2005/Atom">
<id>http://localhost:8890/activities/feeds/activities/user/demo/source/0/10</id>
<updated>2007-11-15T14:25:10.000+02:00</updated>
<category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/activities/2007#activity"/>
<title>I'm at work</title>
<link rel="self" type="application/atom+xml" href="http://localhost:8890/activities/feeds/activities/user/demo/source/0/10"/>
<link rel="edit" type="application/atom+xml" href="http://localhost:8890/activities/feeds/activities/user/demo/source/0/10"/>
<received>2007-11-15T14:25:10.000+02:00</received>
</entry>
</verbatim>

---+++ Retrieving entries

The feed retrieval is just a GET against user activities feed, e.g.,
<verbatim>
GET http://localhost:8890/activities/feeds/activities/user/demo
</verbatim>
produces a Atom feed with users activities listed

---+++ Updating entries

The update is similar to entry creation, but in this case the HTTP method must be PUT and the Atom entry must contain a valid atom:id, for example:

<verbatim>
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://localhost:8890/activities/feeds/activities/user/demo/source/12/8</id>
  <updated>2007-10-27T19:41:51.574Z</updated>
  <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/activities/2007#activity"/>
  <title>Another Edited title</title>
  <link rel="self" type="application/atom+xml" href="http://www.google.com/activities/feeds/activities/user/userID/source/sourceID/a1"/>
  <link rel="edit" type="application/atom+xml" href="http://www.google.com/activities/feeds/activities/user/userID/source/sourceID/a1"/>
  <received>2007-10-27T19:41:51.478Z</received>
</entry>
</verbatim>

---+++ Deleting entries

It's the same as update, just in this case the HTTP method is DELETE. 

In cases where clients do not support PUT/DELETE , the X-HTTP-Method-Override HTTP header is supported; i.e., DELETE can be  represented by :
<verbatim>
POST /url HTTP/1.1
X-HTTP-Method-Override: DELETE
....
</verbatim>


CategoryODS CategoryVirtuoso CategoryOpenSocial CategoryWebSite

%ODSCOPY%