たけまる / OpenSocial Protocol

■ Architecture

基本的には，Client-Server だと思います．

Client (Google Gadget etc.)
  |
OpenSocial Protocol
  |
SNS (Orkut etc.)

Client と Server 間の通信手順やデータフォーマットを定めているのが
OpenSocial Protocol です．

Google は，2 種類の OpenSocial Protocol 実装を発表しています．ひと
つは Client Side で使われ，そのインタフェースが JavaScript API とし
てまとめられています．もうひとつは Server (SNS) Side で使われる
OpenSocial Data APIs です．

プロトコルはオープンなので，第 3 者による実装が登場する可能性もあり
ます．

OpenSocial Protocol では，REST の流儀に従ってリソースを操作します．
つまり，URI でリソースを指定して，HTTP method で操作するということ
です．REST の実装はおおむね Atom Publishing Protocol (AtomPub) に従っ
ています．正確には，AtomPub を拡張した Google Data APIs (GData) に
従っています．

■ Authentication

認証方法については，Orkut の例のみが掲載されています．Orkut は
Google のサービスなので，ClientLogin や AuthSub といった Google
Account の認証方法が使われます．

今後，他の SNS が OpenSocial を実装したときに，どのような認証方法が
使われるのかはわかりません．

■ Data

OpenSocial は 3 種類のデータを扱います．

各種データは AtomPub に従って操作されます．つまり，HTTP POST でデー
タを作成し，GET で取得，PUT で修正，DELETE で削除します．また，特定
の URI に対して GET すると，データ一覧 (Feed) を取得できます．

ここでは，データの概要と URI について説明します．Atom フォーマット
拡張については省略しますので，API Document を参照してください．

■ Data - People

ユーザに関する情報です．次のような例が挙げられています．

Elizabeth の thumbnail は http://... です．居場所は N51,E0 です

AtomPub による操作方法は次の通りです．データを変更することはできな
いようです．

Method + URI	Format	説明
GET /feeds/people/{user-id}	Atom Entry	ユーザ (user-id) の情報を取得
GET /feeds/people/{user-id}/friends	Atom Feed	友だち情報の一覧

■ Data - Activity

Google の Document には user's activity としか書いていないのですが，
実際には日記や写真などのデータ (コンテンツ) を想定していると思いま
す．次のような例が挙げられています．

Liz が YouTube に Darcy とのデート映像をアップしました

AtomPub による操作方法は次の通りです．

Method + URI	Format	説明
GET /activities/feeds/activities/user/{userID}	Atom Feed	データ一覧を取得
POST /activities/feeds/activities/user/{userID}/source/{sourceID}	Atom Entry	データを作成
GET /activities/feeds/activities/user/{userID}/source/{sourceID}	Atom Entry	データを取得
PUT /activities/feeds/activities/user/{userID}/source/{sourceID}	Atom Entry	データを修正
DELETE /activities/feeds/activities/user/{userID}/source/{sourceID}	Atom Entry	データを削除

Activity では，あるユーザに関する更新情報を user-level feed といい
ます．また，ユーザだけでなくデータ源も指定するときには，その更新情
報を source-level feed といいます．上の表では，一番上が user-level
feed であり，それ以外は source-level feed です．

なお，scope (日記の公開範囲) を指定する方法は定められていません．

いくつか，AtomPub と異なる点があるのでコメントしておきます．

AtomPub の用語を用いて正確に定義するなら，user-level feed は
Collection であり，source-leve feed は Collection 中の Entry です．

上の例の POST URI は，正しくは /activities/feeds/activities/user/{userID}
だと思います．AtomPub では，Atom Feed を取得する URI と Atom Entry
を作成する URI は同じになります．また，Entry ID (source ID?) はサー
バが付与するのが普通です．

■ Data - Persistence

アプリケーション固有の情報です．key/value 形式で表します．Windows
Registry みたいなものでしょうか．

Method + URI	Format	説明
GET /feeds/apps/{applicationID}/persistence/global	Atom Feed	データ一覧を取得
POST /feeds/app/{applicationID}/persistence/global	Atom Entry	データを作成
GET /feeds/app/{applicationID}/persistence/global/{key}	Atom Entry	データ (keyに対応する値) を取得
PUT /feeds/app/{applicationID}/persistence/global/{key}	Atom Entry	データ (keyに対応する値) を修正
DELETE /feeds/app/{applicationID}/persistence/global/{key}	Atom Entry	データ (keyに対応する値) を削除

Persistence については query が定義されています．たとえば，次の
query は，ユーザ (userID) の友だちに関するデータのうち，somekey に
合致するもののみを取得します．フォーマットは Atom Feed になります．

/feeds/apps/{applicationID}/persistence/{userID}/friends?key=somekey 

■ Data - GData との関係

OpenSocial は GData に準拠しているそうですが，検索 query (q= など)
のサポートは不明です．サポートが明記してあるのは Persistence の
key= のみです．People についての説明には，"People では query をサポー
トしてない" とあります．

GData では Edit URI の規則が次のように決められていますが，
OpenSocial は必ずしもこの規則に従っていないようです．

Collection URI	http://example.com/myFeed
Edit URI	http://example.com/myFeed/{enryID}/{entryVersion}/

■ 参考

たけまる / Atom Publishing Protocol を勉強するには
たけまる / GData 仕様の和訳 - プロトコル，Common Elements