1. The OpenSocial API CS 195.35: Survey of Contemporary Technologies

2. 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

3. 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

4. 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

5. 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

6. 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, …

7. 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 object is returned

8. 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 that defines the IdSpec; for example: {"userId" : "OWNER", "groupId" : "FRIENDS"}

9. 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

10. Requesting application data newFetchPersonAppDataRequest newUpdatePersonAppDataRequest newRemovePersonAppDataRequest

11. 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 a Map > object

12. 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)

13. 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)

14. 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)

15. 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

16. 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

17. Request items v0.8 People:  newFetchPersonRequest  newFetchPeopleRequest Activities:  newFetchActivitiesRequest Application Data: (persistence)  newFetchPersonAppDataRequest  newUpdatePersonAppDataRequest  newRemovePersonAppDataRequest To be tackled later

18. 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 items to be supported in the future on OpenSocial-ready containers

19. 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

20. References http://wiki.opensocial.org http://wiki.opensocial.org/index.php? title=JavaScript_API_Reference http://wiki.opensocial.org/index.php? title=JavaScript_API_Reference