There are a number of aspects to Open Social, the best known of which is probably the support of 'Gadgets'. These are essentially 'windows' into applications that can be included and aggregated in other applications. However there is also a significant REST API defined in the Open Social standard that allows any developer to interact with an Open Social provider to do things such as create a Microblog entry or add a rich event to the Activity Stream.
Connections provides these API endpoints and in this and the following pages we outline how best to use them.
An Activity Stream is an aggregated stream of events relevant to a given user. At it's simplest it is a list of things that have happened to Objects in which a user has expressed an interest, but it has the ability to reflect people, communities and objects of interest, while also reflecting events happening any where in your enterprise. The Connections Activity Stream appears in 3 places in Connections -
- Your homepage - these are the events in which an interest has been expressed
- Your profile - these are the events involving you (either because they reflect something you did, or because someone wrote to your board)
- Communities - each community has it's own Activity Stream, reflecting activity within the Community.
In addition to providing a brief description regarding an event, an application can also provide an embedded experience that allows a user to interact with the application that posted the event. For example a travel application may post an event to the stream to notify you that a flight you were waiting for has become available. It may also include an embedded experience that allows you to immediately proceed with the booking or cancel, in place, without navigating to the travel application. An embedded experience is implemented as a Gadget (to enable displaying it in another website) along with associated context (to let the Gadget know the specific content for which it has been invoked).
Microblogging is essentially the posting of short text messages that anyone who is following you (or views your profile) can see. Communities also have their own microblogging board that members can post to. If the community is not public, then neither is its board.
OAuth is a means of authorizing an application to act on your behalf. In the context of Open Social (and the Activity Stream) it allows a 3rd Party Application to contact connections and say 'is it ok if I contribute events to User ABC's stream'. Connections will then ask you if you approve, and if you do, this application will be allowed to post events on your behalf (until such time as you revoke the authorization)
REST and REST Client
REST stands for Re
URLs to use
All of the Connections Open Social APIs work from a single root -
- 'context_root' is generally not present (but can be depending on how the server was installed!). Appended to this is the name of the particular API you'd like to use. There are 3 currently supported -
- activitystreams - for viewing and sending rich events to the Activity Stream
- ublog - for viewing and posting status updates and comments
- people - get getting information about the current user
After this, there is normally
the user of interest (typically '@me') followed by
the group of interest (typically '@all')
So for example, if you want to see the current users (@me) most recent activity stream events from all sources (@all) you would make a GET request to -
You can do this GET from a browser (a JSON Viewer plugin will help if you want to see the formatted output). See the individual API definitions for more details.
The above URL will work from a browser where you are logged on as it uses the current users session. However if you are making an API request separately, you will likely need to use some authorization/authentication. Connections supports basic and OAuth authentication/authorization , but each is available on its own URL. The above URL would for example become one of -
See Authentication and Authorization
The data format used is JSON. This makes it simple to write a sample request with for example a REST Client.
In order to ensure (when posting events) that the format is recognised, you need to include the header