Using OpenSocial REST APIs
Added by IBM contributorIBM | Edited by Claudia R Elbourn on July 7, 2015
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

Open Social is a standard API designed to give a social context to business applications.


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.

Some Definitions

Activity Stream

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 -
  1. Your homepage - these are the events in which an interest has been expressed
  2. Your profile - these are the events involving you (either because they reflect something you did, or because someone wrote to your board)
  3. Communities - each community has it's own Activity Stream, reflecting activity within the Community.


A gadget is essentially a Window into an application. It can be as simple as a predefined HTML rendering, or as complex as a full application downloading appropriate Javascript to be fully interactive. Open Social provides a container so that gadgets from many sites can be shown on the same page, and can even interact with the Container, without compromising the security of the containing application.

Embedded Experience

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)


JavaScript Object Notation. This is a data exchange format derived from JavaScript and easily consumed by Javascript. It is the data exchange format used by all of the OpenSocial APIs. Although Atom is partially supported, it is being deprecated.

REST and REST Client

REST stands for Representational State Transfer. It is a style of client-server architecture popular in web applications, that typically see a Web page created by Javascript which in turn calls APIs to get data, rather than having HTML assembled on the server. The server itself remains stateless. A REST Client is a browser plugin that allows easy GETing and POSTing of REST requests.

Where to start



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 for details.

Data format

The data format used is JSON. This makes it simple to write a sample request with for example a REST Client.
See the Quick_Start_45Create New Article for an example.
In order to ensure (when posting events) that the format is recognised, you need to include the header
Content-Type: application/json