The OpenSocial API

CS 195.35: Survey of Contemporary Technologies

Key namespaces

opensocial: defines classes that represent key objects and data in a social networking environment (persons, activities, messages) and functions that facilitate object creation and social data requests

gadget: defines classes and functions that facilitate remote data requests and container-specific user interface features

opensocial.DataRequest

Class that represents a request object opensocial.newDataRequest() returns a new

instance of DataRequest Key methods:

add( item, key ): adds a request item; for fetch data requests, key needs to be indicated for future retrieval

send( callback ): invoked after all request items have been added; data to be processed by call back function

Adding request items

A request object contains one or more request items

Items are added through the add method of DataRequest

Items are created through newFetchXXX, newUpdateXXX and newRemoveXXX methods for Fetch items, data will be retrieved and handled in

the callback function through the key indicated

Fetching person data

newFetchPersonRequest( id, params ): Creates a request item to fetch data on a single

person in the container id is a string representing the person’s id in the

container, or the string ‘VIEWER’ or ‘OWNER’ params can be used to specify which data elements

to retrieve Note: actual data will be retrieved and handled

within the callback function when processed, a Person object is returned

opensocial.Person

getID(): returns the container id of the person(a string)

getDisplayName(): returns the name of the person (a string)

getField( key ): returns some other field For key, use one of the constants defined in

opensocial.Person.Field; for example: ID, NAME, NICKNAME, EMAIL, STATUS, GENDER, …

Fetching people data

newFetchPeopleRequest( idspec, params ) Creates a request item to fetch data on several

people in the container idspec is an IdSpec object specifying which people

to fetch (viewer’s friends or owner’s friends) params can be used to specify which data elements

to retrieve, or restrict the people to some subset Note: actual data will be retrieved within the

callback function when processed, a Collection<Person> object is

returned

opensocial.IdSpec

Class (interface) representing an id specification usually indicating a group of people

IdSpec objects are created using opensocial.newIdSpec( params )params is a Map<string,string>

that defines the IdSpec; for example:{"userId" : "OWNER", "groupId" : "FRIENDS"}

opensocial.Collection

size(): returns size of collection each( function(object) ): calls function on

each object of the collection getById( id ): returns an element of the

collection

Requesting application data

newFetchPersonAppDataRequest newUpdatePersonAppDataRequest newRemovePersonAppDataRequest

Fetching app data

newFetchPersonAppDataRequest( idspec, keys, params) Creates a request item to retrieve app data for

multiple users idspec specifies which persons, keys specifies which

data (‘*’ for all), params enforces some restrictions When processed in callback function, the

request returns aMap< PersonId, Map<String, Object>> object

About app data

The data got there to begin with through newUpdatePersonAppDataRequest

Data (and its associated keys) are application specific (cannot “mix” data between apps)

Setting/updating app data

newUpdatePersonAppDataRequest( id, key, value ) id: string that specifies the person

(e.g., ‘VIEWER’) key: identifies which data will be updated value: the data value

When processed, nothing is returned(no need to handle response in the callback function)

Removing app data

newRemovePersonAppDataRequest( id, keys ) id: string that specifies the person

(e.g., ‘VIEWER’)keys: identifies which data will be removed

When processed, nothing is returned(no need to handle response in the callback function)

opensocial.DataResponse

The callback function takes in a parameter representing a DataResponse object

Methods: get( key ): returns a ResponseItem object; key

should be as indicated during the add invocation hadError(): returns a boolean indicating if an error

occured getErrorMessage(): if an error occurred, returns a

string representing the error message

opensocial.ResponseItem

getData(): returns the data expected from the request Type depends on the request item (could be a

Person, Collection, or Map)

hadError(): returns a boolean indicating if an error occured

getErrorMessage(): if an error occurred, returns a string representing the error message

Request items v0.8

People: newFetchPersonRequest newFetchPeopleRequest

Activities: newFetchActivitiesRequest

Application Data: (persistence) newFetchPersonAppDataRequest newUpdatePersonAppDataRequest newRemovePersonAppDataRequest

To be tackled later

Request items v0.9 People:

newFetchPersonRequest newFetchPeopleRequest

Activities: newFetchActivitiesRequest

Application Data newFetchPersonAppDataRequest newUpdatePersonAppDataRequest newRemovePersonAppDataRequest

Media Items newCreateMediaItemRequest newFetchMediaItemsRequest newUpdateMediaItemRequest

Albums newCreateAlbumRequest newFetchAlbumsRequest newUpdateAlbumRequest newDeleteAlbumRequest

Many other request itemsto be supported in the futureon OpenSocial-ready containers

gadgets.json

Helpful when converting between JavaScript and the application data server

gadgets.json.stringify( object ) object is a JavaScript value/object Returns a JSON string

gadgets.json.parse( str ) str is a JSON string (formed using stringify) Returns a JavaScript value/object

References

http://wiki.opensocial.org http://wiki.opensocial.org/index.php?title=J

avaScript_API_Reference