The OpenSocial API

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<Person> 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<string,string>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 aMap< PersonId, Map<String, Object>> 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 itemsto 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