OpenSocial REST

Apache Shindig implements the OpenSocial Restful Protocol based on AtomPub. It supports XML and JSON formats in addition to Atom format XML. The following REST samples will focus on the Read only operation (GET). All sample data are located in http://localhost:8080/gadgets/files/sampledata/canonicaldb.json.

• Getting all people connected to john.doe:
  • URL: http://localhost:8080/social/rest/people/john.doe/@all
  • Result:

    {"entry":[{"id":"jane.doe","name":{"formatted":"Jane Doe","givenName":"Jane","familyName":"Doe"}},
    {"id":"george.doe","name":{"formatted":"George Doe","givenName":"George","familyName":"Doe"}},
    {"id":"maija.m","name":{"formatted":"Maija Meikäläinen","givenName":"Maija","familyName":"Meikäläinen"}}],"totalResults":3,"startIndex":0}

• Getting the profile of john.doe:
  • URL: http://localhost:8080/social/rest/people/john.doe/@self
  • Result:

    {"entry":{"id":"john.doe","name":{"formatted":"John Doe","givenName":"John","familyName":"Doe"}}}

• Getting all the friends of jane.doe:
  • URL: http://localhost:8080/social/rest/people/jane.doe/@friends
  • Result:

    {"entry":[{"id":"john.doe","name":{"formatted":"John Doe","givenName":"John","familyName":"Doe"}}],"totalResults":1,"startIndex":0}

• Getting the activities of john.doe:
  • URL: http://localhost:8080/social/rest/activities/john.doe/@self
  • Result:

    {"entry":[{"title":"yellow","userId":"john.doe","id":"1","body":"what a color!"}],"totalResults":1,"startIndex":0}

• Getting the activities of john.doe using a security token:
  • URL: http://localhost:8080/social/rest/people/jane.doe/@friends?st=a:a:a:a:a:a:a
  • Result:

    {"entry":[{"title":"yellow","userId":"john.doe","id":"1","body":"what a color!"}],"totalResults":1,"startIndex":0}

For more information on the URI templates, please read OpenSocial REST section in the overview page.

OpenSocial JSON-RPC

Apache Shindig also implements OpenSocial RPC Protocol. The following RPC samples are similar to the REST samples.

• Getting the profile of john.doe:
  • URL: http://localhost:8080/social/rpc?method=people.get&id=myself&params.userId=john.doe&params.groupId=@self
  • Result:

    {"data":{"id":"john.doe","name":{"formatted":"John Doe","givenName":"John","familyName":"Doe"}}}

• Getting all the friends of jane.doe:
  • URL: http://localhost:8080/social/rpc?method=people.get&id=myself&params.userId=john.doe&params.groupId=@all
  • Result:

    {"data":{"list":[{"id":"jane.doe","name":{"formatted":"Jane Doe","givenName":"Jane","familyName":"Doe"}},
    {"id":"george.doe","name":{"formatted":"George Doe","givenName":"George","familyName":"Doe"}},
    {"id":"maija.m","name":{"formatted":"Maija Meikäläinen","givenName":"Maija","familyName":"Meikäläinen"}}],"totalResults":3,"startIndex":0}}

For more information on the URI templates, please read OpenSocial JSON-RPC section in the overview page.

Create Your First OpenSocial Gadget

Apache Shindig implements Gadgets Specification. Gadgets are web-based software components based on HTML, CSS, and JavaScript. Please read Getting Started: gadgets.* API to learn more.

Typically, an Opensocial gadget is similar to a Google Gadget since its should respect the Google Gadgets specifications. Here is a small snippet:

<?xml version="1.0" encoding="UTF-8"?>
<Module>
  <ModulePrefs title="A Title">
    <Require feature="opensocial-0.8"/>
    ...
  </ModulePrefs>
  <Content type="html">
     <![CDATA[
     <script type="text/javascript">
       ...
       gadgets.util.registerOnLoadHandler(init);
     </script>
     <div id="id"/>
     ...
     ]]>
  </Content>
</Module>

This XML file describes the OpenSocial application.

• The ModulePrefs section contains application metadata, such as title and required libraries. Also, you would notice the require element which includes the OpenSocial APIs as feature. Always declaring this requirement make your applications as an OpenSocial application. Others features supported by Apache Shindig are described here.
• The application contents live within the Content section. You should include additional JavaScript that contains the application logic and an handler to fire an init() function at launch time with the gadgets.util.registerOnLoadHandler() function. Finally, you will include an HTML section to display the result.

To access data from the Apache Shindig, you have to create a DataRequest object using the opensocial.newDataRequest() call.

Your first application will enumerate the friends currently belonging to the network of the user accessing the application. The following snippet is the code of http://localhost:8080/gadgets/files/samplecontainer/examples/getFriendsHasApp.xml.

<?xml version="1.0" encoding="UTF-8"?>
<Module>
  <ModulePrefs title="List Friends using HAS_APP filter Example">
    <Require feature="opensocial-0.7"/>
  </ModulePrefs>
  <Content type="html">
  <![CDATA[
    <script type="text/javascript">
      /**
       * Request for friend information.
       */
      function getData() {
        var req = opensocial.newDataRequest();

        req.add(req.newFetchPersonRequest(opensocial.DataRequest.PersonId.OWNER), 'owner');
        var params = {};
        params[opensocial.DataRequest.PeopleRequestFields.MAX] = 50;
        params[opensocial.DataRequest.PeopleRequestFields.FILTER] = opensocial.DataRequest.FilterType.HAS_APP;
        params[opensocial.DataRequest.PeopleRequestFields.SORT_ORDER] = opensocial.DataRequest.SortOrder.NAME;
        req.add(req.newFetchPeopleRequest(opensocial.DataRequest.Group.OWNER_FRIENDS, params), 'ownerFriends');
        req.send(onLoadFriends);
      };

      /**
       * Parses the response to the friend information request and generates
       * html to list the friends along with their display name.
       *
       * @param {Object} dataResponse Friend information that was requested.
       */
      function onLoadFriends(dataResponse) {
        var owner = dataResponse.get('owner').getData();
        var html = 'Friends of ' + owner.getDisplayName();
        html += ':<br><ul>';
        var ownerFriends = dataResponse.get('ownerFriends').getData();
        ownerFriends.each(function(person) {
          html += '<li>' + person.getDisplayName() + '</li>';
        });
        html += '</ul>';
        document.getElementById('message').innerHTML = html;
      };

      gadgets.util.registerOnLoadHandler(getData);
    </script>
    <div id="message"> </div>
  ]]>
  </Content>
</Module>

The following is the result of http://localhost:8080/gadgets/files/samplecontainer/examples/getFriendsHasApp.xml in the sample container http://localhost:8080/gadgets/files/samplecontainer/samplecontainer.html:

This is your first overview of the APIs that deals with people and relationships.

To go further, you could also try the opensocialdevapp http://osda.appspot.com/gadget/osda-0.8.xml, for instance:

http://localhost:8080/gadgets/ifr?url=http://osda.appspot.com/gadget/osda-0.8.xml&view=canvas

Create Your Own OpenSocial Back-end

Apache Shindig implements Opensocial Specification.

Typically, you need to implement some classes: PersonService, AppDataService, ActivityService, MessagesService, AlbumService, GroupService, MediaItemService.

In Java, theses classes are located in the org.apache.shindig.social.opensocial.spi package. Apache Shindig proposes a sample JPA implementation. Read Samples for Java for more information.

In PHP, theses classes are located in the social/opensocial/spi dir.

Resources

• OpenSocial Tutorial